> ## Documentation Index
> Fetch the complete documentation index at: https://www.conductor.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Asynchronous queries

> Understand the async execution model for long-running Data API 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.

<Note>
  Currently, all endpoints in the Data API require async queries.
</Note>

## 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

| 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

<Steps>
  <Step title="Submit the initial query">
    Include all required query parameters specific to the endpoint.

    ```bash theme={null}
    curl -X POST "https://api-universal.conductor.com/data-api/v1/keyword_rankings?apiKey=${API_KEY}&sig=your-signature" \
      -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.*

    ```json theme={null}
    {
      "executionId": "abc123",
      "executionState": "IN_PROGRESS"
    }
    ```
  </Step>

  <Step title="Poll for results">
    Use the `executionId` you received. Drop the main query parameters and only send the ID.

    ```bash theme={null}
    curl -X POST "https://api-universal.conductor.com/data-api/v1/keyword_rankings?apiKey=${API_KEY}&sig=your-signature" \
      -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.
  </Step>

  <Step title="Fetch the next page">
    If your `200 OK` response included a `nextPageId`, include it alongside your `executionId` to pull the next chunk of data.

    ```bash theme={null}
    curl -X POST "https://api-universal.conductor.com/data-api/v1/keyword_rankings?apiKey=${API_KEY}&sig=your-signature" \
      -H "Content-Type: application/json" \
      -d '{
        "executionId": "abc123",
        "nextPageId": "page2"
      }'
    ```
  </Step>
</Steps>

<Note>
  **Need help?** Reach out to the Data Platform Team: [data-platform@conductor.com](mailto:data-platform@conductor.com)
</Note>