Skip to main content

Documentation Index

Fetch the complete documentation index at: https://conductor.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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]