Reports — TokenID

Generate a management report

POST/api/v1/reports/management

Generates a branded PDF report and returns it as application/pdf.

Request body

Field	Type	Required	Description
`from`	ISO 8601 date	Yes	Start of the reporting period
`to`	ISO 8601 date	Yes	End of the reporting period (inclusive)
`sections`	array of strings	No	Sections to include. Defaults to all five sections.

Valid sections values: summary, spend, violations, enforcement, reconciliation.

Example

curl -X POST https://token.audit.id/api/v1/reports/management \
  -H "Authorization: Bearer td_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-04-01","to":"2026-04-30"}' \
  --output report.pdf

Response

Content-Type: application/pdf — binary PDF file.

A X-Report-Id header is included in the response. Use it to retrieve the report later.

List reports

GET/api/v1/reports

Returns metadata for all reports generated in the last 90 days.

Response

{
  "reports": [
    {
      "id": "rpt_01abc…",
      "period_from": "2026-04-01",
      "period_to": "2026-04-30",
      "sections": ["summary","spend","violations","enforcement","reconciliation"],
      "generated_at": "2026-05-01T08:00:00Z",
      "expires_at": "2026-07-30T08:00:00Z",
      "size_bytes": 148320
    }
  ]
}

Download a report

GET/api/v1/reports/{report_id}

Downloads a previously generated report by ID.

curl https://token.audit.id/api/v1/reports/rpt_01abc \
  -H "Authorization: Bearer td_live_xxxx" \
  --output report.pdf

Returns 404 if the report has expired or does not exist.

Get report branding

GET/api/v1/reports/branding

Returns the current branding configuration for your account.

{
  "logo_url": "https://token.audit.id/assets/orgs/abc123/logo.png",
  "brand_color": "#3B5BF6",
  "org_name": "Acme Corp",
  "footer_text": "Acme Corp — Confidential"
}

Update report branding

POST/api/v1/reports/branding

Upload a logo and set brand colour. All fields are optional — omit to leave unchanged.

Field	Type	Description
`logo`	file	PNG or SVG. Max 2 MB.
`brand_color`	string	Hex colour code, e.g. `#3B5BF6`
`org_name`	string	Displayed on the cover page
`footer_text`	string	Custom footer. Defaults to org name + `token.audit.id`

curl -X POST https://token.audit.id/api/v1/reports/branding \
  -H "Authorization: Bearer td_live_xxxx" \
  -F "logo=@acme-logo.png" \
  -F "brand_color=#E85D2F" \
  -F "org_name=Acme Corp"

Chargeback / showback report

GET/api/v1/reports/chargeback

Returns spend aggregated by a tag dimension over the requested window — useful for sub-organisation chargeback, project-level showback, or per-model cost attribution. JSON by default, CSV on demand.

Query parameters

Parameter	Type	Default	Description
`dimension`	string	`model`	Grouping dimension. One of `provider`, `model`, `api_key_hash`, `team_id`, `feature`, `project_id`.
`start_date`	ISO 8601 date	—	Start of window (inclusive). Used together with `end_date`.
`end_date`	ISO 8601 date	—	End of window (inclusive).
`period`	string	`30d`	Shorthand window when `start_date`/`end_date` are omitted. One of `today`, `7d`, `30d`, `90d`.
`format`	string	`json`	Response format. One of `json`, `csv`.

Response (JSON)

{
  "organization_id": "01HXY…",
  "dimension": "model",
  "since": "2026-04-21T00:00:00+00:00",
  "until": "2026-05-21T00:00:00+00:00",
  "count": 4,
  "total_cost_cents": 81450,
  "total_cost_usd": 814.5,
  "buckets": [
    {
      "bucket": "claude-opus-4-7",
      "cost_cents": 52310,
      "cost_usd": 523.1,
      "tokens": 18420000,
      "rows": 1284
    }
  ]
}

Buckets are ordered by cost_cents descending. Rows with a NULL dimension value (e.g. an event with no team_id) collapse into a single bucket labelled <unset>.

Example — JSON by team

curl "https://token.audit.id/api/v1/reports/chargeback?dimension=team_id&period=30d" \
  -H "Authorization: Bearer td_live_xxxx"

Example — CSV download by model

curl "https://token.audit.id/api/v1/reports/chargeback?dimension=model&period=30d&format=csv" \
  -H "Authorization: Bearer td_live_xxxx" \
  --output chargeback.csv

CSV responses set Content-Disposition: attachment with the filename chargeback-{dimension}-{from}-{to}.csv. Columns: {dimension}, cost_cents, cost_usd, tokens, rows.