Skip to main content
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

  1. Initial Request: Submit your query parameters. The API returns a 202 Accepted status along with an executionId.
  2. 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.
  3. 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

FieldDescription
executionIdThe unique identifier for tracking your specific query.
executionStateThe current status: either "IN_PROGRESS" or "COMPLETED".
nextPageIdA token for retrieving the next page of results (when available).

​
Walkthrough

1

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?apiKey=${API_KEY}&sig=your-signature" \
  -H "X-API-GATEWAY-KEY: ${API_KEY}" \
  -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"
}
2

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?apiKey=${API_KEY}&sig=your-signature" \
  -H "X-API-GATEWAY-KEY: ${API_KEY}" \
  -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.
3

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?apiKey=${API_KEY}&sig=your-signature" \
  -H "X-API-GATEWAY-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "executionId": "abc123",
    "nextPageId": "page2"
  }'
Need help? Reach out to the Data Platform Team: [email protected]