# 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/`**](#submit-one-time-query) call to submit your new query and receive a **query ID**.
2. Run a [**`/status/`**](#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/`**](#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 %}