GET /v1/reports/*

Every dashboard view is also an endpoint, queryable with the same Bearer token. Plug it into PowerBI, Looker, Excel, or your own dashboard.

The reports endpoints are Pro and above. Free orgs get /v1/reports/usage for their own quota state.

Common parameters

All endpoints below accept these query params:

Param	Default	Values
`period`	`30d`	`24h`, `7d`, `30d`, `90d`, `ytd`, `all`
`agent_id`	(none)	Filter to one agent
`task_type`	(none)	Filter to one task type
`format`	`json`	`json` or `csv`

GET /v1/reports/time-saved

Hours saved + cost saved, grouped by one or more dimensions.

Param	Default	Values
`group_by`	`agent`	Comma-list of `agent`, `task_type`, `client`, `day`, `week`, `month`
`sort`	`hours_saved`	`hours_saved`, `cost_saved`, `events`
`top`	(none)	Limit to top N rows

curl "https://humanhours.dev/v1/reports/time-saved?period=30d&group_by=agent,task_type&sort=hours_saved&top=20" \
  -H "Authorization: Bearer $HUMANHOURS_API_KEY"

GET /v1/reports/cost-saved

Cost saved + agent cost + net saved. Same dimensions as /time-saved; default sort is cost_saved.

curl "https://humanhours.dev/v1/reports/cost-saved?period=30d&group_by=client" \
  -H "Authorization: Bearer $HUMANHOURS_API_KEY"

net_saved = cost_saved - agent_cost. Useful for finance views: "we saved €18k of human time but spent €1.2k on inference, net €16.8k".

GET /v1/reports/leaderboard

Rank agents by a single metric.

Param	Default	Values
`metric`	`hours_saved`	`hours_saved`, `cost_saved`, `events`

curl "https://humanhours.dev/v1/reports/leaderboard?metric=cost_saved&period=90d" \
  -H "Authorization: Bearer $HUMANHOURS_API_KEY"

GET /v1/reports/export

Same shape as time-saved but always emits CSV with a Content-Disposition: attachment header so a browser downloads instead of rendering. Convenient for "send the CFO the spreadsheet" flows.

GET /v1/reports/usage

Open to all plans. Returns the org's current period state.

{
  "plan": "pro",
  "currency": "EUR",
  "events_this_month": 24310,
  "events_included_in_plan": 100000,
  "overage_events": 0,
  "lifetime_events": 318211,
  "projected_overage_eur": null
}

projected_overage_eur is null when no overage is forecast; otherwise it shows the projected charge at the end of the billing period using the graduated metered tiers.

Response shape

All endpoints (except /usage) return:

{
  "meta": {
    "period": "30d",
    "range": { "from": "2026-04-06T00:00:00Z", "to": "2026-05-06T00:00:00Z" },
    "group_by": ["agent"],
    "sort": "hours_saved",
    "total_groups": 7
  },
  "currency": "EUR",
  "rows": [
    {
      "group": { "agent_id": "support-classifier" },
      "events": 4310,
      "hours_saved": 286.7,
      "cost_saved": 12901.5,
      "agent_cost": 124.3,
      "net_saved": 12777.2
    }
  ]
}

CSV format

When format=csv, the response is a UTF-8 CSV with a header row. Group columns come first, then the metric columns. The Bearer token works the same way in ?format=csv mode.