Analytics

Create analytics web report

Creates a shareable Analytics v2 web report and returns its bearer-like access token and URL. The body is validated before anything is rendered, so a malformed request fails with INVALID_FIELD instead of quietly producing a wrong report for your end client. from and to are calendar dates in YYYY-MM-DD; a full ISO timestamp is accepted and truncated to its date, and anything else is refused rather than treated as "no filter" (which used to widen the report to the account's entire history). An inverted window (from after to) is refused too. template is a published enum — executive, agency, creator, minimal, growth, board — and an unknown value is refused instead of becoming executive. brandAccent must be #rrggbb (#rgb is expanded); named colours, rgb() and 8-digit hex are refused instead of being replaced by the TokPortal default. White-labelling still depends on entitlement: brandName and brandAccent only apply on the full analytics tier with a Farmer plan, and are otherwise reset. The response carries applied — the template, brand name, brand accent and the exact date window the report covers — plus canBrand, so read those back instead of inspecting the rendered report. Do not send Idempotency-Key. The successful response contains a secret and is never stored in the replay ledger. A request with the header is rejected with IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE (400) before any ledger claim or operation execution.

post/analytics/export/reports

Request

  • Base URL: https://app.tokportal.com/api/ext
  • URL: https://app.tokportal.com/api/ext/analytics/export/reports
  • Auth: API key in header X-API-Key

Headers

X-TokPortal-Dry-Run'true' | '1' | 'yes'

Send true (or 1/yes) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds dry_run: true, dry_run_notice, and — on credit-spending operations — credits_would_charge carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).

Request body

titlestring nullable

Report title. 120 characters, the real stored limit.

template'executive' | 'agency' | 'creator' | 'minimal' | 'growth' | 'board' | 'null' nullable

Report layout. Any other value is rejected with INVALID_FIELD rather than silently becoming executive. The applied template is echoed as applied.template on the JSON response and as X-TokPortal-Report-Template on the HTML export.

brandNamestring nullable

White-label brand name (80 characters, the real stored limit). Applied only on the full analytics tier with a Farmer plan; on every other plan it is reset to TokPortal, and the response says so through applied.brand_name and canBrand — check them before promising a client a white-labelled document.

brandAccentstring nullable

White-label accent colour, #rrggbb (a #rgb short form is expanded). Named colours, rgb() and 8-digit hex are rejected with INVALID_FIELD instead of silently becoming the TokPortal default. Like brandName it only applies on a Farmer plan at the full tier; read applied.brand_accent back.

accountIdsstring[]
workspaceIdstring uuid nullable
platformsstring[]
countriesstring[]
querystring nullable

Free-text filter. 120 characters, the real stored limit.

fromstring date nullable

Inclusive start date, YYYY-MM-DD. A full ISO timestamp is accepted and truncated to its date; anything else is rejected with INVALID_FIELD rather than silently treated as no filter (which used to widen the report to the account's entire history). Must not be after to. The window actually applied comes back as applied.filters.from.

tostring date nullable

Inclusive end date, YYYY-MM-DD, same parsing as from. Echoed as applied.filters.to.

Response

Created analytics report.

object required

Changes

No recorded changes to this operation across all 1 revision of this API.