Execute a Report

Create a new report job

📘

Supported Regions and Base URLs

👍

Access and Registration

Authentication

🚧

Transport Layer Security 1.2 (TLS) is the minimum version of the TLS protocol allowed for use on the Explore API endpoints.

Scope

data-reports:write

Body Request - Example

{
  "name": "string",
  "timezone": "string",
  "format": "csv",
  "timespan": {
    "from": "2019-08-24T14:15:22Z",
    "to": "2019-08-24T14:15:22Z"
  }
}

Body Response - Schema

202 (job accepted)

ParameterTypeDescriptionRequired
idstringthe job IDno
namestringreport's nameno
timezonestringtimezone in IANA format which the report timespan (from and to) will be applied
statusstringReport status indicating the workflow progress.
Allowed values: "created",
"processing", "uploading",
"done", "failed", "canceled", "deleted"
no
formatstringFormat in which the report file will be created.
Allowed values: "csv", "json", "json_bulk"
no
timespanobjectTime range to filter for the report content.

"timespan" subdivides into:

1 - "from" (string
)
- start datetime filter for the records to be retrieved from the report.

2 - "to" (string
)
- end datetime filter for the records to be retrieved from the report.

Note: In order to ensure non-overlapping time ranges, our timespan uses an inclusive start (“from >=”) and an exclusive end (“to <”).
no

400 (bad request), 401 (unauthorized), 403 (inputs misconfiguration), 429 (too many requests), 503 (unable to audit operation)

ParameterTypeDescriptionRequired
codestringn/ayes
descriptionstringn/ayes
messagestringn/ano
fieldsarray[object]"fields" subdivides into:

"name" (string)

"description" (string)
yes (name and description)

🚧

Report Availability and Data Latency

You can't download a custom or default report or dashboard created in Explore via the Explore API. The reports that can be extracted via Explore API are:

The report file will be available for download for 30 days.
The data obtained via the Explore API may have a 5-minute delay compared to real-time.

❗️

Account-based Quota

The Explore API has an account-based quota limit of 15 simultaneous reports (executing + enqueued). If this limit is exceeded, the user will receive a 429 (too many requests) response.

❗️

A Request to Execute a Report May Fail When

  • The credentials are not valid or the required scope is missing.
  • The report request:
    • Does not have a valid structure.
    • Is missing a mandatory field.
  • Some report request field has an invalid value (e.g.: invalid report format or not properly formatted date time).
  • The report's end date (timespan.to) is:
    • Prior to the start date (timespan.from).
  • The difference in days between the end date (timespan.to) and the start date (timespan.from) is greater than 31.
  • The report's timezone is not a valid timezone. Only timezones that follows the IANA standard are allowed.
  • The account-based quota limit of 15 simultaneous reports (executing + enqueued) has been exceeded.

🚧

Troubleshooting

If you have any questions regarding the usage of this API, or if you’re having any technical issues, please open a ticket using this form.

Language
Authorization
Header
Click Try It! to start a request and see the response here!