Agent: Statistics

These endpoints return cross-session usage aggregates: a per-session rollup scoped by working directory and realm, plus global usage rollups by (provider, account) and by (model, provider). Use them to surface per-session activity, per-account audits, and per-model cost or latency reporting. The cross-session statistics endpoint scopes by cwd by default and accepts realm selectors; the usage rollups are cwd-independent and global, so they accept no realm scope.

Cross-session statistics

Returns the cross-session usage aggregate: per-session counters rolled up over persisted records.

`GET /api/v1/agent/statistics`

Returns the cross-session usage aggregate: per-session counters rolled up over persisted records. The scope query parameter defaults to cwd; realm selection uses X-Hoody-Realm (header, wins) or ?realm= (query alias). When the realm selector is omitted, the agent’s own realm is used.

cURL
TypeScript SDK

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/statistics?scope=cwd" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -H "X-Hoody-Realm: global"

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.stats.get({
  scope: 'cwd',
  'X-Hoody-Cwd': '/home/user/project',
  'X-Hoody-Realm': 'global',
});

Parameters

Name	In	Type	Required	Description
`scope`	query	string	No	`cwd` (default) rolls up the current working directory; `all` rolls up every session.
`realm`	query	string	No	Per-request realm selector: `"global"` or a 24-hex realm id. Query alias of `X-Hoody-Realm` (read only when the header is absent).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope: the `.hoody` project layer, the record cwd, or the tool and workflow cwd.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override selecting which on-disk `.hoody` install a stateless read or write resolves against.
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex realm id. Wins over the `realm` query parameter. When omitted, the agent’s own realm is used.

Response

{
  "scope": "cwd",
  "cwd": "/home/user/project",
  "totals": {
    "sessions": 12,
    "messages": 145
  }
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request scope header this route does not take: a realm or container header on a route without that dimension, or, on an agent pinned to one realm, a different realm.	Omit the header, or name the realm the agent is pinned to.
`invalid_realm`	Invalid realm selector	The realm selector is malformed (not `""`, `"global"`, or a 24-hex id).	Pass a valid realm selector.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (Source IP Guard)	Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.	Call the agent through its URL, for example with `hoody agent …`.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "restriction_unknown",
  "message": "the login's realm restriction could not be read — retry"
}

Error Code	Title	Description	Resolution
`restriction_unknown`	Login restriction unknown	The agent cannot read yet which realms its login may serve (`GET /hoody/auth/status` reports restriction `"unknown"`), so it refuses realm-scoped requests until it can. Nothing was read or changed.	Retry after the restriction is readable.

Usage rollup by account

Returns a per-(provider, account) usage rollup from the global usage store.

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

Returns a per-(provider, account) usage rollup from the global usage store. Accepts ?since=<unix-seconds> to set the lower bound (omit for all-time; a negative or non-numeric value is rejected 400). Because the usage store is global and not realm-scoped, a realm header is rejected with 400 realm_scope_unsupported.

cURL
TypeScript SDK

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/usage/by-account?since=1700000000" \
  -H "Authorization: Bearer $HOODY_TOKEN"

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.usage.listByAccount({
  since: 1700000000,
});

Parameters

Name	In	Type	Required	Description
`since`	query	integer	No	Unix-seconds lower bound; omit for all-time. A negative or non-numeric value is rejected `400`.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope: the `.hoody` project layer, the record cwd, or the tool and workflow cwd.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override selecting which on-disk `.hoody` install a stateless read or write resolves against.

Response

{
  "accounts": [
    {
      "provider": "openai",
      "account": "team@example.com",
      "calls": 1247,
      "success": 1218,
      "errors": 29
    }
  ]
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request scope header this route does not take: a realm or container header on a route without that dimension, or, on an agent pinned to one realm, a different realm.	Omit the header, or name the realm the agent is pinned to.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (Source IP Guard)	Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.	Call the agent through its URL, for example with `hoody agent …`.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

Usage rollup by model

Returns a per-(model, provider) usage rollup from the global usage store: calls, success rate, cost, and latency.

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

Returns a per-(model, provider) usage rollup from the global usage store: calls, success rate, cost, and latency. Accepts ?since=<unix-seconds> (omit for all-time; a negative or non-numeric value is rejected 400). Because the usage store is global, cwd-independent, and not realm-scoped, a realm header returns 400 realm_scope_unsupported and the rollup is identical regardless of the active realm.

cURL
TypeScript SDK

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/usage/by-model" \
  -H "Authorization: Bearer $HOODY_TOKEN"

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.usage.listByModel();

Parameters

Name	In	Type	Required	Description
`since`	query	integer	No	Unix-seconds lower bound; omit for all-time. A negative or non-numeric value is rejected `400`.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope: the `.hoody` project layer, the record cwd, or the tool and workflow cwd.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override selecting which on-disk `.hoody` install a stateless read or write resolves against.

Response

{
  "models": [
    {
      "provider": "openai",
      "model": "gpt-4o",
      "calls": 1247,
      "success_rate": 0.977,
      "cost_usd": 12.45,
      "latency_ms": 850
    }
  ]
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request scope header this route does not take: a realm or container header on a route without that dimension, or, on an agent pinned to one realm, a different realm.	Omit the header, or name the realm the agent is pinned to.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (Source IP Guard)	Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.	Call the agent through its URL, for example with `hoody agent …`.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.