One-time Queries

Learn how to use our three one-time query endpoints to submit a new query, check the query run status, and fetch the completed query results.
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:
Run a /submit/ call to submit your new query and receive a query ID.
Run a /status/ 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.
Once the status of your query is completed, run a /fetch/ call with the original query ID to download your completed query results.
get
Submit One-time Query
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 they 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.
Request
Response
Request
Path Parameters
endpoint
required
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
apikey
required
string
Your Chartbeat API key
sort_column
required
string
Must match a value in your metrics or dimensions parameter
sort_order
required
string
Either asc or desc
start
required
string
YYYY-MM-DD
end
required
string
YYYY-MM-DD
endpoint
required
string
Either page or video
host
required
string
The site on which you are querying
limit
required
integer
Base-10 values only
tz
required
string
The timezone you'd like to run the query in a valid Olson timezone format, e.g. America/New_York.
metrics
required
string
Comma-separated values
dimensions
optional
string
Comma-separated values
{filter}=
optional
string
Will filter data on the passed-in filter_value
Response
200: OK
Returns a query ID for use in your subsequent calls to the status and fetch endpoints. Example ID:
{query_id: "4ed64430-9049-469b-8eee-e38d265017dc"}
get
Get Status of One-time Query
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.
Request
Response
Request
Query Parameters
query_id
required
string
Value returned from call to /submit/ endpoint
host
required
string
The site you are querying
apikey
required
string
Your Chartbeat API key
Response
200: OK
{
    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
}
​
get
Fetch One-time Query
https://api.chartbeat.com/query/v2/fetch/
The /fetch/ endpoint will return the data for a completed query (default is in .csv format).
Request
Response
Request
Query Parameters
query_id
required
string
Value returned from call to /submit/ endpoint
host
required
string
The site you are querying
apikey
required
string
Your Chartbeat API key
format
optional
string
Set to json to return data formatted in JSON instead of CSV
Response
200: OK
Returns the traffic data from your query!
//Will return .csv formatted data, unless providing format=json parameter
API Docs - Previous
Historical API
Recurring Queries
Last updated 1 month ago
One-time Queries

getSubmit One-time Query

getGet Status of One-time Query

getFetch One-time Query

get
Submit One-time Query

get
Get Status of One-time Query

get
Fetch One-time Query
