# One-time Queries
**One-time queries** are good for pulling data over custom date ranges. One-time queries must be submitted anew for every unique run if your team wants to run the same report (using the same metrics, dimensions, and/or filters) over unique date ranges (using unique start and end date parameters).
Getting data back from a one-time query is a three-step process using each of the below one-time API endpoints:
1. Run a [**`/submit/`**](/cbp/api/historical-api/one-time-queries.md#submit-one-time-query) call to submit your new query and receive a **query ID**.
2. Run a [**`/status/`**](/cbp/api/historical-api/one-time-queries.md#get-status-of-one-time-query) call to check the status of your submitted query using the **query ID** from your previous call to the `/submit/` endpoint. Continue running as frequently as every ten seconds or so until you receive a `completed` status for your query.
3. Once the status of your query is `completed`, run a [**`/fetch/`**](/cbp/api/historical-api/one-time-queries.md#fetch-one-time-query) call with the original **query ID** to download your completed query results.
## Submit One-time Query
`GET` `https://api.chartbeat.com/query/v2/submit/`
Submitting a query to the `/submit/` endpoint will initiate your query run. More complex queries may take several minutes to complete. The expected return value of this call is a `query_id` that can be used to both check the status of your query as well as to access the returned data.\
\
The "filter" parameter is a stand-in for the dimension-parameter you want to filter by. To include a filter in your submitted query, use `dimension` as the query param key, and set it to a value (or multiple values) to filter by for that query.\
\
**Note:** Metrics and dimensions should be declared before including filters. They accept a comma separated list of values.
#### Path Parameters
| Name | Type | Description |
| -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| endpoint | string | Append `page/` or `video/` to the endpoint URL above after `/submit/`, before appending query parameters below. This determines whether your API call will query page or video data. The endpoint query parameter below is also required. |
#### Query Parameters
| Name | Type | Description |
| ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apikey (*see note*) | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/historical-api/getting-started-with-our-historical-api#required-parameters) |
| sort\_column | string | **Must match a value in your metrics or dimensions parameter** |
| sort\_order | string | Either `asc` or `desc` |
| start | string | YYYY-MM-DD |
| end | string | YYYY-MM-DD |
| endpoint | string | Either `page` or `video` |
| host | string | The site on which you are querying |
| limit | integer | Base-10 values only |
| tz | string | The timezone you'd like to run the query in a valid Olson timezone format, e.g. America/New\_York. |
| metrics | string | Comma-separated values |
| dimensions | string | Comma-separated values |
| {filter}= | string | `{filter}` is a placeholder value. Choose from our list of filter parameters (see the final page of this guide), and pass in a filter value. For example: `§ion=news` |
{% tabs %}
{% tab title="200 Returns a query ID for use in your subsequent calls to the status and fetch endpoints. Example ID:" %}
```scheme
{query_id: "4ed64430-9049-469b-8eee-e38d265017dc"}
```
{% endtab %}
{% endtabs %}
## Get Status of One-time Query
`GET` `https://api.chartbeat.com/query/v2/status/`
Use the `/status/` endpoint to check on the status of your query. If you are programmatically querying Chartbeat data, you should wait until your `status` value returns "completed" before making the fetch call (see below), or you will get an error.\
\
Possible status responses include submitted, running, completed, downloaded, and deleted.
#### Query Parameters
| Name | Type | Description |
| ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query\_id | string | Value returned from call to `/submit/` endpoint |
| host | string | The site you are querying |
| apikey (*see note*) | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/historical-api/getting-started-with-our-historical-api#required-parameters) |
{% tabs %}
{% tab title="200 " %}
```scheme
{
status: "", //submitted, running, completed, downloaded, or deleted
metrics: [
//list of metrics being returned in the query
],
host: "YOURSITE.com",
query_id: "4ed64430-9049-469b-8eee-e38d265017dc", //<-example query ID
dimensions: [
//list of dimensions being returned in the query
],
query_num: null
}
```
{% endtab %}
{% endtabs %}
## Fetch One-time Query
`GET` `https://api.chartbeat.com/query/v2/fetch/`
The `/fetch/` endpoint will return the data for a completed query (default is in .csv format).
#### Query Parameters
| Name | Type | Description |
| ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query_id` | string | Value returned from call to `/submit/` endpoint |
| `host` | string | The site you are querying |
| `format` | string | Set to `json` to return data formatted in JSON instead of CSV |
| apikey (*see note*) | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/historical-api/getting-started-with-our-historical-api#required-parameters) |
{% tabs %}
{% tab title="200 Returns the traffic data from your query!" %}
```
//Will return .csv formatted data, unless providing format=json parameter
```
{% endtab %}
{% endtabs %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.chartbeat.com/cbp/api/historical-api/one-time-queries.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.