Making queries - Conductor Documentation

Queries made to the Data API should have some specific considerations. Read on:

Asynchronous queries

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).

Date range and `collection_frequency`

Data API endpoints collect results on a fixed cadence, so your submitted date range must align with that cadence. Requests that don’t align are rejected before the query runs.

`collection_frequency`	Start-date rule	End-date rule
`WEEKLY`	Must be a Sunday	Must be a Saturday
`MONTHLY`	Must be the first day of a month	Must be the last day of a month

Some endpoints use start_date / end_date, while others (such as ai_search_response) use time_period_start / time_period_end. The alignment rules above apply either way — check the endpoint reference for the exact field names.

Reading results (schema-driven rows)

Completed responses return data as positional tuple rows plus a schema array that lists each column’s name and type in order. The available columns — and therefore the metrics you get back (such as mentions, citations, sentiment score, or share of voice) — are defined by the schema in each response, not by a static list in the docs. To see the exact metrics your query returned, read the column names from schema and pair them with the values in each row.

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]

​Asynchronous queries

​The async lifecycle

​Response fields

​Date range and collection_frequency

​Reading results (schema-driven rows)

​Walkthrough

Asynchronous queries

The async lifecycle

Response fields

Date range and `collection_frequency`

Reading results (schema-driven rows)

Walkthrough