Concepts

humanhours sits between your agents and your CFO. You send one HTTP call per task; we compute "how long would a human have taken" and "what did that cost", and serve the numbers back as a dashboard, a weekly digest, and a Reports API.

What gets stored per event

{
  agent_id:                  string,         // your stable id, e.g. "support-classifier"
  task_type:                 string,         // controlled vocabulary, e.g. "email_classification"
  outcome:                   "success" | "failure" | "needs_review",
  agent_duration_seconds?:   number,         // how long the agent took
  agent_cost?:               number,         // what the agent run cost in your currency
  human_baseline_minutes?:   number,         // override the default baseline for this event only
  metadata?:                 object,         // free-form, e.g. { client_id, channel, model }
  audit_sample?: {
    input_excerpt?:  string,
    output_excerpt?: string,
    model?:          string,
    tokens_in?:      number,
    tokens_out?:     number,
  },
  occurred_at?:              ISO 8601,       // defaults to server-time on receipt
}

agent_id, task_type, and outcome are required. Everything else is optional; defaults make the lazy path work.

Task types and baselines

Every task type ships with a default baseline (in minutes), cited from public benchmarks (McKinsey 2024, Worklytics 2025, Anthropic Economic Index 2024) or Triad pilots. 50 task types are seeded out of the box across eight categories: support, ops, sales, legal, content, research, data, dev.

You can do three things to a baseline:

• Use as-is — start here. The baseline is publicly cited.
• Override per workspace — change the value for your org while keeping the original on record.
• Create a custom task type — when nothing in the catalogue fits.

Both override and custom require Pro. The lazy default is "use as-is".

What we compute

hours_saved = max(0, baseline_minutes - agent_duration_seconds / 60) / 60
cost_saved  = hours_saved * hourly_rate
net_saved   = cost_saved - (agent_cost || 0)

hourly_rate resolves in this order: per-agent override → org default → €45/h fallback. baseline_minutes resolves in this order: request override → org override → builtin → reject.

Audit trail (the CFO-proof layer)

When you send an audit_sample (input excerpt, output excerpt, model, token counts), we store it next to the event. The CFO link and the dashboard then show a sample of "what the agent actually did" so finance can spot-check claims. This is Pro-only; on Free, the field is silently dropped.

Quotas and overage

The dashboard's /reports/usage tab shows your real-time month-to-date count and the projected overage in dollars.

Open spec, hosted layer

The wire format and error envelope are versioned (/v1/...) and stable. When /v2 lands, /v1 keeps working for at least 12 months. The reference implementation, the SDKs, and the protocol document are open source; the hosted humanhours.dev is the revenue layer (PostHog / Segment / OpenTelemetry pattern).