Everything Analytics counts is open to your own systems: list the
reports your account can run, run one for any period as JSON or CSV, count anything a
source offers with a query of your own, and have
scheduled reports arrive at your webhooks.
You need a key with the reports:read scope (see
Keys and scopes). Keys made before reports existed don’t
have it: add it to the key.
The reports you can run
GET /v1/reports lists the built-in reports and those your
team saved and shared with everyone. A key has no person behind it, so it never sees a
report someone kept to themselves — share it in the panel to run it here.
Running one
GET /v1/reports/{report_id} answers a report’s columns,
rows and totals — for the period it is saved with, or another:
Reading an answer:
- Rates are fractions (
0.926 is 92.6%), money is in minor units of currency,
durations are in seconds. Each column’s format says which.
- Days are the account’s, in its time zone.
- A report grouped by something other than time keeps its top rows and adds up the rest in
one
Other row.
- In a CSV file, figures are written as people read them instead: rates as percentages,
money in whole units.
A query of your own
When no saved report fits, POST /v1/reports/run counts
whatever a source offers, without saving anything.
GET /v1/reports/sources lists each source’s
dimensions (to group and filter by) and measures (to count):
A query that asks for something a source doesn’t have is refused with invalid_request,
and field names what is wrong.
Any tool that can read a web address with an Authorization header can pull a report —
the JSON answer for tools that read JSON, format=csv for those that read files. Save a
report in the panel with the measures and groups you want, share it, and point the tool at
its address with a relative period (preset=30d, preset=last_month) so each refresh
brings the latest figures.
Give the tool its own key with only reports:read, so it can read figures and nothing
else. A refresh counts towards the key’s rate limit like any request.
Scheduled reports to your webhooks
A schedule can send its report to your
webhook endpoints as a report.delivered event, signed and
retried like every other. Add the event to an endpoint first; a schedule can only send
to webhooks once one listens.
rows carries up to 1,000 rows. When there are more, rows_complete is false and
rows_total says how many: fetch the whole file from file.url with
GET /v1/reports/files/{file_id}, using your key.previous and change are there when the report compares.- If no endpoint listens for the event when the schedule runs, the run fails and says so;
after five failures in a row the schedule is switched off.
