Asynchronous report exports: queue one, then poll it until its file is ready.
List report exports
Returns the organization's report exports in the workspace, newest first. Each item is the export as GET /reports/exports/{id} returns it; download_url appears only on a ready export. Filter by status (comma-separated for several).
Required scope: analytics.read (Read analytics).
query Parameters
limitPage size (default 50, max 200).
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
statusFilter by status, comma-separated for several (status=ready,failed). Also status.ne=expired.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List report exports › Responses
OK
Queue a report export
Renders a metric series to CSV asynchronously and returns a presigned download link when it is ready.
WHY ASYNCHRONOUS. A dashboard query is bounded — a chart nobody can render is worse than no chart — but an export has nobody watching, produces a file, and is usually wanted over a range no interactive query should attempt. Forcing both through one path means either the dashboard can hang or the export cannot cover a year.
AN IDENTICAL REQUEST IS REUSED. Asking twice for the same metric, grain, currency, range and dimension returns the export already pending or ready rather than rendering it again. A failed or expired one is not reused, so asking again after a failure means what you intend.
TWO IDENTICAL EXPORTS PRODUCE IDENTICAL BYTES, and therefore an identical sha256. Rows are sorted, buckets are rendered in UTC, values come from exact decimals rather than floats, and no run timestamp appears in the file — so the digest means 'the same data', not 'the same moment'.
Required scope: report.export (Export reports).
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Queue a report export › Request Body
currencyISO 4217 code.
fromInclusive start, YYYY-MM-DD.
grainBucket width. WEEK is the ISO week (Monday 00:00 in the bucketing timezone through Sunday), derived from the day grain; QUARTER and YEAR are derived from the month grain.
metricMetric key, as listed by GET /analytics/metrics.
toExclusive end, YYYY-MM-DD.
dimensionOptional dimension to slice by.
timezoneIANA zone for bucket boundaries. Defaults to the organization's.
Queue a report export › Responses
OK
Get a report export
Polls one export. download_url appears only once the status is ready, and expires with the export rather than later — a presigned link outliving the record it came from is tenant financial data reachable after the system stopped tracking that it was.
An id belonging to another organization answers 404 rather than 403: one that resolves for one tenant and forbids for another is an existence oracle.
Required scope: analytics.read (Read analytics).
path Parameters
idHeaders
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a report export › Responses
OK