Search Jobs API: Running and Automating Long-Running Searches Programmatically

If you need to run searches asynchronously or execute queries over extended time ranges programmatically or via a script, you can leverage the Search Jobs API, which is exposed via GraphQL. This approach is particularly useful for long-running or resource-intensive searches that may not complete within the standard synchronous search flow.

Creating a Search Job

To initiate a search job, use the following GraphQL mutation:


mutation CreateSearchJob($query: String!) {
  createSearchJob(query: $query) {
    id
  }
}

Example variables:


{
  "query": "type:diff file:dockerfile after:\"1 day ago\""
}

This mutation returns a job id, which you can use to monitor progress and retrieve results.

Retrieving Search Job Results

Once the job has been created, you can query its status and obtain the result and log URLs via GraphQL:


curl -X POST \
  -H "Authorization: token <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  https://your-sourcegraph-url.com/.api/graphql \
  -d '{
    "query": "query GetSearchJob($id: ID!) { node(id: $id) { ... on SearchJob { id state URL logURL } } }",
    "variables": { "id": "<JOB_ID>" }
  }'

Downloading Results and Logs

Using the URLs returned in the previous step, you can download the search results and logs via authenticated HTTP requests:

Download results (JSONL format):


curl -H "Authorization: token <YOUR_TOKEN>" \
  https://your-instance.com/.api/search/export/<JOB_ID>.jsonl > results.jsonl

Download logs:


curl -H "Authorization: token <YOUR_TOKEN>" \
  https://your-instance.com/.api/search/export/<JOB_ID>.log > logs.log

Summary

Use the Search Jobs API for asynchronous or long-running searches
Create a job via GraphQL and capture the returned id
Query the job status to retrieve result and log URLs
Download outputs directly using authenticated HTTP requests

This workflow provides a reliable and scalable way to execute and retrieve large search queries outside of the standard synchronous search experience via the UI.