Skip to content
Hoody Documentation
Download Page (.md)

The Agent Statistics API exposes cross-session usage aggregates and rollups for the Hoody platform. Use these endpoints to power dashboards, billing reconciliation, and observability tooling. The statistics.aggregate route rolls up per-session counters over persisted records, while usage.by_account and usage.by_model surface per-account and per-model rollups from the daemon-global usage_calls store.

Cross-session statistics

Section titled “Cross-session statistics”

GET /api/v1/agent/statistics

Section titled “GET /api/v1/agent/statistics”

Returns the cross-session usage aggregate (the statistics.aggregate daemon action): per-session counters rolled up over persisted records. The scope query parameter selects between the current working directory (cwd, default) and every session (all).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
scopequerystringNocwd (default) rolls up the current working directory; all rolls up every session.
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1): the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1) selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1): "global" or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realmquerystringNoPer-request realm selector (§6.1) — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): "global" or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Response

Section titled “Response”

Statistics report. The response body is a verbatim daemon reply; the field set is the forwarded daemon action’s own.

{
  "scope": "cwd",
  "sessions": 42,
  "totalCalls": 1847,
  "totalInputTokens": 482934,
  "totalOutputTokens": 198234,
  "totalCostUsd": 23.47,
  "byModel": {
    "claude-opus-4-6": {
      "calls": 234,
      "inputTokens": 102938,
      "outputTokens": 38291,
      "costUsd": 18.2
    },
    "claude-sonnet-4-5": {
      "calls": 1613,
      "inputTokens": 379996,
      "outputTokens": 159943,
      "costUsd": 5.27
    }
  }
}

Example request

Section titled “Example request”
Terminal window
curl -G https://api.hoody.ai/api/v1/agent/statistics \
  --data-urlencode "scope=cwd" \
  -H "X-Hoody-Cwd: /home/user/project"

Usage rollup by account

Section titled “Usage rollup by account”

GET /api/v1/agent/usage/by-account

Section titled “GET /api/v1/agent/usage/by-account”

Returns the per-(provider, account) usage rollup from the daemon-global usage_calls store. Optionally bound by ?since= (Unix seconds) to filter out records older than the given timestamp. Omit since for all-time. This is a net-new daemon RPC (usage.by_account) and is global/no-realm: supplying a realm header returns 400 realm_scope_unsupported.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
sincequeryintegerNoUnix-seconds lower bound; omit for all-time. A negative or non-numeric value is rejected (400).
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1): the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1) selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1): "global" or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realmquerystringNoPer-request realm selector (§6.1) — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): "global" or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Response

Section titled “Response”

Per-account rollup. The response body is a verbatim daemon reply; the field set is the forwarded daemon action’s own.

{
  "accounts": [
    {
      "provider": "anthropic",
      "accountId": "acc_main",
      "calls": 1204,
      "successCount": 1198,
      "errorCount": 6,
      "inputTokens": 298123,
      "outputTokens": 128443,
      "costUsd": 19.83
    },
    {
      "provider": "openai",
      "accountId": "acc_backup",
      "calls": 643,
      "successCount": 643,
      "errorCount": 0,
      "inputTokens": 184811,
      "outputTokens": 69791,
      "costUsd": 3.64
    }
  ]
}

Example request

Section titled “Example request”
Terminal window
curl -G https://api.hoody.ai/api/v1/agent/usage/by-account \
  --data-urlencode "since=1700000000"

Usage rollup by model

Section titled “Usage rollup by model”

GET /api/v1/agent/usage/by-model

Section titled “GET /api/v1/agent/usage/by-model”

Returns the per-(model, provider) usage rollup from the daemon-global usage_calls store: call counts, success rate, cost, and latency. Optionally bound by ?since= (Unix seconds) to filter out records older than the given timestamp; default is all-time. The usage store is daemon-global, cwd-independent, and not realm-scoped, so a realm header returns 400 realm_scope_unsupported and the rollup is identical regardless of the active realm. This is a net-new daemon RPC (usage.by_model).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
sincequeryintegerNoUnix-seconds lower bound; omit for all-time. A negative or non-numeric value is rejected (400).
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1): the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1) selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1): "global" or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realmquerystringNoPer-request realm selector (§6.1) — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): "global" or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Response

Section titled “Response”

Per-model rollup. The response body is a verbatim daemon reply; the field set is the forwarded daemon action’s own.

{
  "models": [
    {
      "model": "claude-opus-4-6",
      "provider": "anthropic",
      "calls": 234,
      "successCount": 231,
      "errorCount": 3,
      "successRate": 0.987,
      "inputTokens": 102938,
      "outputTokens": 38291,
      "costUsd": 18.2,
      "avgLatencyMs": 4321,
      "p95LatencyMs": 7820
    },
    {
      "model": "claude-sonnet-4-5",
      "provider": "anthropic",
      "calls": 1613,
      "successCount": 1613,
      "errorCount": 0,
      "successRate": 1.0,
      "inputTokens": 379996,
      "outputTokens": 159943,
      "costUsd": 5.27,
      "avgLatencyMs": 1834,
      "p95LatencyMs": 3211
    }
  ]
}

Example request

Section titled “Example request”
Terminal window
curl -G https://api.hoody.ai/api/v1/agent/usage/by-model \
  --data-urlencode "since=1700000000"