Skip to content

Run a report

POST
/stores/{storeRef}/reports/run
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

storeRef
required
string

The store’s ref, as returned by GET /stores.

format
string
Allowed values: csv

Set to csv to receive a CSV file instead of JSON.

Media typeapplication/json
object
dimensions

Dimensions to group by, at most 4, without duplicates.

Array<object>
object
grain

Time grain for a date dimension: day, week, month, quarter or year.

string
Allowed values: day week month quarter year
field
required

Key of a dimension of the dataset.

string
<= 100 characters
filters

Conditions that narrow the rows.

Array<object>
object
operator
required

How to compare: is, is_not, gte or lte. Which of them a filter accepts is listed in the report schema.

string
<= 100 characters
Allowed values: is is_not gte lte
values
required

The values to compare with, up to the limit the filter allows. Numbers and booleans are read as text.

Array
field
required

Key of a filter of the dataset.

string
<= 100 characters
date_range
required

The days the report covers.

object
start
required

First day, inclusive, as YYYY-MM-DD in the store’s time zone.

string
end
required

Last day, inclusive, as YYYY-MM-DD in the store’s time zone. At most 5 years after start.

string
sort

How to sort the rows.

Array<object>
object
order
required

Sort direction.

string
Allowed values: asc desc
key
required

Key of a selected measure or dimension to sort by.

string
<= 100 characters
visualization

How the dashboard draws the report: table, line or bar. It does not change the rows.

string
Allowed values: table line bar
v

Version of the definition format. The API always reads it as the current version.

number
dataset
required

Key of the dataset to read, such as orders. Dataset keys are listed in the report schema.

string
<= 100 characters
measures
required

Keys of the measures to calculate, from 1 to 8, without duplicates.

Array<string>
limit

Maximum number of rows, from 1 to 1000. Defaults to 100.

number
>= 1 <= 1000

The report as JSON, or as a CSV file when format=csv.

object
columns
required

The columns, in order.

Array<object>
object
role
required

Whether the column groups rows (dimension) or is calculated (measure).

string
Allowed values: dimension measure
type
required

Value type. money values are in the report’s currency.

string
Allowed values: money integer string date id
grain

Time grain of a date column.

string
Allowed values: day week month quarter year
alias
required

Name of this column’s key in each row.

string
key
required

Key of the measure or dimension the column shows.

string
label_key
required

Translation key of the column’s label.

string
label_alias

Name of the column in each row that holds a display name for an id column.

string
rows
required

The rows. Each row is an object keyed by column alias.

Array<object>
object
key
additional properties
nullable
One of:
string
definition
required

The definition as the API understood it, which you can save as it is.

object
dimensions
required

Dimensions to group by.

Array<object>
object
grain

Time grain for a date dimension: day, week, month, quarter or year.

string
Allowed values: day week month quarter year
field
required

Key of a dimension of the report’s dataset.

string
filters
required

Conditions that narrow the rows.

Array<object>
object
operator
required

How the values are compared.

string
Allowed values: is is_not gte lte
field
required

Key of a filter of the report’s dataset.

string
values
required

The values to compare with. is and is_not match any of the values.

Array<string>
date_range
required

The days the report covers.

object
start
required

First day, inclusive, as YYYY-MM-DD in the store’s time zone.

string
end
required

Last day, inclusive, as YYYY-MM-DD in the store’s time zone.

string
sort
required

How the rows are sorted.

Array<object>
object
order
required

Sort direction.

string
Allowed values: asc desc
key
required

Key of a selected measure or dimension.

string
visualization

How the dashboard draws the report. It does not change the rows.

string
Allowed values: table line bar
v
required

Version of the definition format.

number
dataset
required

Key of the dataset the report reads, such as orders.

string
measures
required

Keys of the measures to calculate.

Array<string>
limit
required

Maximum number of rows.

number
currency
required

The currency of every money column, or null when the report has none.

string
nullable
row_count
required

Number of rows returned.

number
truncated
required

True when the row limit was reached, so more rows exist. Narrow the report to see them.

boolean

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.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

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.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}