Model cost and net ROI · HumanHours docs

net_saved is the number your CFO cares about: the money an agent saved, minus what the agent run cost. HumanHours can work out that cost for you from the model and token usage, so you get a true net ROI without doing any pricing maths.

How the cost is resolved

When you call POST /v1/track, the run cost (agent_cost) is resolved in this order:

`resolved_cost_source`	When	What happens
`provided`	You pass `agent_cost`	Used exactly as given.
`computed`	You pass `model` + `tokens_in` / `tokens_out` (and no `agent_cost`)	Cost = `tokens_in × input_price + tokens_out × output_price`, converted to your workspace currency.
`none`	Neither of the above, or the model is not in the price book	No cost is recorded; `net_saved` equals `cost_saved`.

net_saved = cost_saved − agent_cost. A value you pass always wins over the computed one.

The model name to use

Important

Pass the model's OpenRouter id, for example anthropic/claude-opus-4.8 or openai/gpt-4o. Matching is exact, so the id has to be spelled exactly as OpenRouter lists it.

Two ways to find the right id:

Browse the priced models page here, search for your model, and copy its id.
Or look it up on openrouter.ai/models and copy the id from the model page.

If the id is not recognised, the run is simply recorded with resolved_cost_source: none, never with an invented cost.

Prices update themselves

The price book is synced every day from OpenRouter's public model pricing. That means:

New models are priced automatically. A model that launches today is available the next day, no action from you.
Price changes are picked up automatically. You never maintain a price list.

Note

The cost is computed and frozen on the event at the moment you track it, together with the exact prices used. Later price changes only affect new events, so your historical ROI never shifts under you.

Example

curl -X POST https://humanhours.dev/api/v1/track \
  -H "Authorization: Bearer $HUMANHOURS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "support-classifier",
    "task_type": "email_classification",
    "outcome": "success",
    "agent_duration_seconds": 4,
    "model": "anthropic/claude-opus-4.8",
    "tokens_in": 1800,
    "tokens_out": 120
  }'

The response carries the resolved cost and its source:

{
  "cost_saved": 2.97,
  "agent_cost": 0.0072,
  "resolved_cost_source": "computed",
  "net_saved": 2.9628,
  "currency": "EUR"
}

ROI per model

Because the model is stored on every event, you can break any report down by it:

curl "https://humanhours.dev/api/v1/reports/cost-saved?group_by=model" \
  -H "Authorization: Bearer $HUMANHOURS_API_KEY"

That tells you which models actually pay for themselves, and which ones cost more than they save.