Quickstart

60 seconds from a signed-in dashboard to a tracked event. Every example below uses the same Bearer token.

1. Get an API key

Go to /api-keys in the dashboard and click Create key. The raw key is shown once. Copy it.

export HUMANHOURS_API_KEY=hh_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Track your first event

curl -X POST https://humanhours.dev/v1/track \
  -H "Authorization: Bearer $HUMANHOURS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-first-agent",
    "task_type": "email_classification",
    "outcome": "success",
    "agent_duration_seconds": 4
  }'

Response:

{
  "event_id": "evt_01HXY...",
  "agent_id": "my-first-agent",
  "task_type": "email_classification",
  "outcome": "success",
  "resolved_baseline_minutes": 4.0,
  "resolved_baseline_source": "builtin",
  "resolved_hourly_rate": 45,
  "currency": "EUR",
  "agent_duration_seconds": 4,
  "hours_saved": 0.066,
  "cost_saved": 2.97,
  "agent_cost": null,
  "net_saved": 2.97,
  "occurred_at": "2026-05-06T10:42:00.000Z"
}

The dashboard at /overview ticks immediately via Supabase Realtime — refresh and you'll see the event.

3. Pull a report

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

That's the full loop: one HTTP call to record, one to read. Everything else (custom task types, weekly digests, share-with-CFO links, webhook fan-out) is layered on top of these two endpoints.

Three adoption levels

humanhours is designed so you can start lazy and tighten as you grow.

Level	Effort	What you send	What you get
Lazy (80%)	1 line	`agent_id`, `task_type`, `outcome`	Hours + cost saved using built-in baselines
Serious (15%)	+ segmentation	+ `agent_duration_seconds`, `metadata` (client_id, channel, …)	Multi-dim breakdowns by agent, task type, client
CFO-proof (5%)	+ per-org overrides	+ `audit_sample` (input/output excerpt, model, tokens)	Full audit trail, custom baselines per workspace

Next steps

SDKs — typed wrappers for JS, Python, n8n, Claude Agent SDK, Vercel AI SDK
Webhooks — push events to Slack, Datadog, your own pipeline
Reports API — pull into PowerBI, Looker, or Excel