Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

The Agent Statistics endpoints expose cross-session usage aggregates and global rollups from the agent daemon. Use these to retrieve per-session counters for a working directory, per-(provider, account) usage totals, or per-(model, provider) rollups that include call counts, success rate, cost, and latency. All three endpoints live behind the agent container’s public host and return the daemon’s reply verbatim.

GET /api/v1/agent/statistics

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

Returns the cross-session usage aggregate. By default, the rollup is scoped to the current working directory (scope=cwd); pass scope=all to roll up every session.

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: 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 selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: 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 — 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”
{
  "scope": "cwd",
  "aggregate": {
    "totalSessions": 42,
    "totalMessages": 387,
    "totalInputTokens": 84521,
    "totalOutputTokens": 40059,
    "totalCost": 18.42,
    "byModel": {
      "claude-3-5-sonnet": {
        "calls": 215,
        "inputTokens": 51200,
        "outputTokens": 23021,
        "cost": 12.45
      },
      "claude-3-haiku": {
        "calls": 172,
        "inputTokens": 33321,
        "outputTokens": 17038,
        "cost": 5.97
      }
    }
  }
}

SDK Usage

Section titled “SDK Usage”
await client.agent.statistics.getStatistics()

With an explicit scope:

await client.agent.statistics.getStatistics({ scope: "all" })

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

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

Per-(provider, account) usage rollup from the global usage store. Pass ?since=<unix-seconds> to filter to records on or after that timestamp; omit since for all-time data. This is a global, no-realm route, so a realm header is rejected with 400 realm_scope_unsupported.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
sincequeryintegerNoUnix-seconds lower bound; omit for all-time. A negative/non-numeric value is rejected 400.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: 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 selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: 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 — 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”
{
  "since": 1704067200,
  "rollups": [
    {
      "provider": "anthropic",
      "account": "ops@example.com",
      "calls": 215,
      "inputTokens": 51200,
      "outputTokens": 23021,
      "cost": 12.45,
      "lastUsed": 1716240000
    },
    {
      "provider": "openai",
      "account": "ops@example.com",
      "calls": 89,
      "inputTokens": 31200,
      "outputTokens": 14118,
      "cost": 4.21,
      "lastUsed": 1716153600
    }
  ]
}

SDK Usage

Section titled “SDK Usage”
await client.agent.statistics.usageByAccount()

With a since filter:

await client.agent.statistics.usageByAccount({ since: 1704067200 })

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

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

Per-(model, provider) usage rollup from the global usage store, including calls, success rate, cost, and latency. Pass ?since=<unix-seconds> to filter to records on or after that timestamp; omit since for all-time data.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
sincequeryintegerNoUnix-seconds lower bound; omit for all-time. A negative/non-numeric value is rejected 400.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: 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 selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: 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 — 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”
{
  "since": 1704067200,
  "rollups": [
    {
      "model": "claude-3-5-sonnet",
      "provider": "anthropic",
      "calls": 215,
      "successRate": 0.981,
      "inputTokens": 51200,
      "outputTokens": 23021,
      "cost": 12.45,
      "avgLatencyMs": 1823,
      "p95LatencyMs": 3450
    },
    {
      "model": "gpt-4o",
      "provider": "openai",
      "calls": 89,
      "successRate": 0.966,
      "inputTokens": 31200,
      "outputTokens": 14118,
      "cost": 4.21,
      "avgLatencyMs": 2104,
      "p95LatencyMs": 4187
    }
  ]
}

SDK Usage

Section titled “SDK Usage”
await client.agent.statistics.usageByModel()

With a since filter:

await client.agent.statistics.usageByModel({ since: 1704067200 })