Asynchronous queries - Conductor Developer Experience

For queries that process large amounts of data, the Data API uses an asynchronous execution model. Instead of holding your connection open (and risking a timeout), you submit a query, receive a tracking ID, and poll for the results at your own pace.

Currently, all endpoints in the Data API require async queries.

The async lifecycle

Initial Request: Submit your query parameters. The API returns a 202 Accepted status along with an executionId.
Polling: Send the executionId back to the endpoint. If it’s still processing, you’ll get another 202 Accepted. Once finished, you’ll get a 200 OK with your data.
Pagination: If your results are large, the completed response includes a nextPageId. Pass this token in your next request to pull the following page of results.

Response fields

Field	Description
`executionId`	The unique identifier for tracking your specific query.
`executionState`	The current status: either `"IN_PROGRESS"` or `"COMPLETED"`.
`nextPageId`	A token for retrieving the next page of results (when available).

Walkthrough

These examples authenticate with a Conductor API token. Still using the legacy API key + signature method? See Authentication for the equivalent request format.

Submit the initial query

Include all required query parameters specific to the endpoint.

curl -X POST "https://api-universal.conductor.com/data-api/v1/keyword_rankings" \
  -H "Authorization: Bearer YOUR_CONDUCTOR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2025-01-01",
    "end_date": "2025-03-01",
    "min_rank": 1,
    "collection_frequency": "WEEKLY"
  }'

Save the executionId from this response for the next step.

{
  "executionId": "abc123",
  "executionState": "IN_PROGRESS"
}

Poll for results

Use the executionId you received. Drop the main query parameters and only send the ID.

curl -X POST "https://api-universal.conductor.com/data-api/v1/keyword_rankings" \
  -H "Authorization: Bearer YOUR_CONDUCTOR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "executionId": "abc123"
  }'

Still running? Expect a 202 response with executionState: "IN_PROGRESS".
Finished? Expect a 200 response with executionState: "COMPLETED" and your data payload.

Fetch the next page

If your 200 OK response included a nextPageId, include it alongside your executionId to pull the next chunk of data.

curl -X POST "https://api-universal.conductor.com/data-api/v1/keyword_rankings" \
  -H "Authorization: Bearer YOUR_CONDUCTOR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "executionId": "abc123",
    "nextPageId": "page2"
  }'

Need help? Reach out to the Data Platform Team: [email protected]

​The async lifecycle

​Response fields

​Walkthrough

The async lifecycle

Response fields

Walkthrough