Run a report
const url = 'https://apibase.ecomweb.app/api/v1/stores/example/reports/run?format=csv';const options = { method: 'POST', headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'}, body: '{"dimensions":[{"grain":"day","field":"example"}],"filters":[{"operator":"is","values":["example"],"field":"example"}],"date_range":{"start":"example","end":"example"},"sort":[{"order":"asc","key":"example"}],"visualization":"table","v":1,"dataset":"example","measures":["example"],"limit":1}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'https://apibase.ecomweb.app/api/v1/stores/example/reports/run?format=csv' \ --header 'Content-Type: application/json' \ --header 'x-api-key: <x-api-key>' \ --data '{ "dimensions": [ { "grain": "day", "field": "example" } ], "filters": [ { "operator": "is", "values": [ "example" ], "field": "example" } ], "date_range": { "start": "example", "end": "example" }, "sort": [ { "order": "asc", "key": "example" } ], "visualization": "table", "v": 1, "dataset": "example", "measures": [ "example" ], "limit": 1 }'Runs a report definition and returns its columns and rows; nothing is saved. Rows are limited by limit (up to 1000), and truncated tells you when the limit cut the result. The date range is at most 5 years, and days are read in the store’s time zone. Add format=csv to download a CSV file of up to 10,000 rows instead of JSON. Take the dataset, measure, dimension and filter keys from the report schema.
Required scopes: read:analytics
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The store’s ref, as returned by GET /stores.
Query Parameters
Section titled “Query Parameters”Set to csv to receive a CSV file instead of JSON.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Dimensions to group by, at most 4, without duplicates.
object
Time grain for a date dimension: day, week, month, quarter or year.
Key of a dimension of the dataset.
Conditions that narrow the rows.
object
How to compare: is, is_not, gte or lte. Which of them a filter accepts is listed in the report schema.
The values to compare with, up to the limit the filter allows. Numbers and booleans are read as text.
Key of a filter of the dataset.
The days the report covers.
object
First day, inclusive, as YYYY-MM-DD in the store’s time zone.
Last day, inclusive, as YYYY-MM-DD in the store’s time zone. At most 5 years after start.
How to sort the rows.
object
Sort direction.
Key of a selected measure or dimension to sort by.
How the dashboard draws the report: table, line or bar. It does not change the rows.
Version of the definition format. The API always reads it as the current version.
Key of the dataset to read, such as orders. Dataset keys are listed in the report schema.
Keys of the measures to calculate, from 1 to 8, without duplicates.
Maximum number of rows, from 1 to 1000. Defaults to 100.
Responses
Section titled “Responses”The report as JSON, or as a CSV file when format=csv.
object
The columns, in order.
object
Whether the column groups rows (dimension) or is calculated (measure).
Value type. money values are in the report’s currency.
Time grain of a date column.
Name of this column’s key in each row.
Key of the measure or dimension the column shows.
Translation key of the column’s label.
Name of the column in each row that holds a display name for an id column.
The definition as the API understood it, which you can save as it is.
object
Dimensions to group by.
object
Time grain for a date dimension: day, week, month, quarter or year.
Key of a dimension of the report’s dataset.
Conditions that narrow the rows.
object
How the values are compared.
Key of a filter of the report’s dataset.
The values to compare with. is and is_not match any of the values.
The days the report covers.
object
First day, inclusive, as YYYY-MM-DD in the store’s time zone.
Last day, inclusive, as YYYY-MM-DD in the store’s time zone.
How the rows are sorted.
object
Sort direction.
Key of a selected measure or dimension.
How the dashboard draws the report. It does not change the rows.
Version of the definition format.
Key of the dataset the report reads, such as orders.
Keys of the measures to calculate.
Maximum number of rows.
The currency of every money column, or null when the report has none.
Number of rows returned.
True when the row limit was reached, so more rows exist. Narrow the report to see them.
Example
{ "columns": [ { "role": "dimension", "type": "money", "grain": "day" } ], "definition": { "dimensions": [ { "grain": "day" } ], "filters": [ { "operator": "is" } ], "sort": [ { "order": "asc" } ], "visualization": "table" }}The request is malformed or failed validation.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The key is missing, invalid, revoked or expired.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}