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

Agent: Statistics

Section titled “Agent: Statistics”

Cross-session agent statistics and usage rollups. These endpoints return aggregate counters persisted by the agent daemon — session-level statistics, usage rollups grouped by provider/account, and usage rollups grouped by model/provider. Use them to build dashboards, cost reports, or to query historical activity from outside an active session.

Get cross-session statistics

Section titled “Get cross-session statistics”

GET /api/v1/agent/statistics

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

Returns the cross-session usage aggregate — per-session counters rolled up over persisted records. Use ?scope=cwd (default) to roll up the current working directory, or ?scope=all to roll up every session. A realm header is rejected on this route.

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.
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.
realmquerystringNoQuery 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.

Request body

Section titled “Request body”

This endpoint accepts no request body.

Response

Section titled “Response”
{
  "scope": "cwd",
  "cwd": "/home/user/projects/acme-app",
  "sessionCount": 47,
  "totalTokens": 1284932,
  "totalCostUsd": 18.42,
  "byModel": [
    {
      "model": "claude-sonnet-4-20250514",
      "provider": "anthropic",
      "calls": 312,
      "tokens": 891244,
      "costUsd": 12.16
    },
    {
      "model": "gpt-4o",
      "provider": "openai",
      "calls": 188,
      "tokens": 393688,
      "costUsd": 6.26
    }
  ],
  "byDay": [
    {
      "date": "2026-01-15",
      "calls": 22,
      "tokens": 64120,
      "costUsd": 0.94
    },
    {
      "date": "2026-01-16",
      "calls": 31,
      "tokens": 88442,
      "costUsd": 1.27
    }
  ],
  "lastUpdatedAt": "2026-01-18T22:14:03.000Z"
}

SDK usage

Section titled “SDK usage”
import { HoodyClient } from 'hoody-sdk';


const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });


await client.agent.statistics.getStatistics({ scope: 'cwd' });

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 a per-(provider, account) usage rollup from the global usage store. Pass ?since=<unix-seconds> to bound the lower timestamp; omit it for all-time. A realm header returns 400 realm_scope_unsupported because the global usage store has no realm dimension.

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.
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.
realmquerystringNoQuery 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.

Request body

Section titled “Request body”

This endpoint accepts no request body.

Response

Section titled “Response”
{
  "since": 1736899200,
  "totals": {
    "calls": 500,
    "tokens": 1284932,
    "costUsd": 18.42
  },
  "accounts": [
    {
      "provider": "anthropic",
      "account": "team-prod@acme.com",
      "calls": 312,
      "tokens": 891244,
      "costUsd": 12.16,
      "successRate": 0.987
    },
    {
      "provider": "openai",
      "account": "team-prod@acme.com",
      "calls": 188,
      "tokens": 393688,
      "costUsd": 6.26,
      "successRate": 0.995
    }
  ],
  "generatedAt": "2026-01-18T22:14:03.000Z"
}

SDK usage

Section titled “SDK usage”
import { HoodyClient } from 'hoody-sdk';


const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });


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

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 a per-(model, provider) usage rollup from the global usage store — call counts, success rate, cost, and latency. Pass ?since=<unix-seconds> (default all-time). The usage store is global and cwd-independent and is not realm-scoped, so a realm header returns 400 realm_scope_unsupported and the rollup is identical regardless of the active realm.

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.
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.
realmquerystringNoQuery 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.

Request body

Section titled “Request body”

This endpoint accepts no request body.

Response

Section titled “Response”
{
  "since": 1736899200,
  "totals": {
    "calls": 500,
    "successRate": 0.990,
    "tokens": 1284932,
    "costUsd": 18.42,
    "avgLatencyMs": 1842
  },
  "models": [
    {
      "model": "claude-sonnet-4-20250514",
      "provider": "anthropic",
      "calls": 312,
      "successRate": 0.987,
      "tokens": 891244,
      "costUsd": 12.16,
      "avgLatencyMs": 1612,
      "p95LatencyMs": 4088
    },
    {
      "model": "gpt-4o",
      "provider": "openai",
      "calls": 188,
      "successRate": 0.995,
      "tokens": 393688,
      "costUsd": 6.26,
      "avgLatencyMs": 2204,
      "p95LatencyMs": 5512
    }
  ],
  "generatedAt": "2026-01-18T22:14:03.000Z"
}

SDK usage

Section titled “SDK usage”
import { HoodyClient } from 'hoody-sdk';


const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });


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