# Agent: Statistics

**Page:** api/agent/statistics

[Download Raw Markdown](./api/agent/statistics.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



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`

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

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `scope` | query | string | No | `cwd` (default) rolls up the current working directory; `all` rolls up every session. |
| `X-Hoody-Cwd` | header | string | No | Per-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-Dir` | header | string | No | Per-request `--config-dir` override selecting which on-disk `.hoody` install a stateless read/write resolves (`HoodyPaths`). |
| `X-Hoody-Container` | header | string | No | Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension. |
| `X-Hoody-Realm` | header | string | No | Per-request realm selector: `global` or a 24-hex id (also accepted as `?realm=`). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes. |
| `realm` | query | string | No | Per-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



```json
{
  "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
      }
    }
  }
}
```


```json
{
  "code": "bad_request",
  "message": "invalid scope value"
}
```

| 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 realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope. | Omit the realm header on this route, or open a session to scope by realm. |


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

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `forbidden` | Forbidden (not via the Hoody proxy) | Forbidden — the request did not reach the service through the public endpoint. | Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly. |


```json
{
  "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. |


```json
{
  "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. |



### SDK Usage

```ts
await client.agent.statistics.getStatistics()
```

With an explicit scope:

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

---

## `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

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `since` | query | integer | No | Unix-seconds lower bound; omit for all-time. A negative/non-numeric value is rejected 400. |
| `X-Hoody-Cwd` | header | string | No | Per-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-Dir` | header | string | No | Per-request `--config-dir` override selecting which on-disk `.hoody` install a stateless read/write resolves (`HoodyPaths`). |
| `X-Hoody-Container` | header | string | No | Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension. |
| `X-Hoody-Realm` | header | string | No | Per-request realm selector: `global` or a 24-hex id (also accepted as `?realm=`). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes. |
| `realm` | query | string | No | Per-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



```json
{
  "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
    }
  ]
}
```


```json
{
  "code": "bad_request",
  "message": "invalid since value"
}
```

| 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 realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope. | Omit the realm header on this route, or open a session to scope by realm. |


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

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `forbidden` | Forbidden (not via the Hoody proxy) | Forbidden — the request did not reach the service through the public endpoint. | Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly. |


```json
{
  "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. |


```json
{
  "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. |



### SDK Usage

```ts
await client.agent.statistics.usageByAccount()
```

With a `since` filter:

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

---

## `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.


The usage store is global, cwd-independent, and not realm-scoped. The rollup is identical regardless of the active realm, and a realm header on this route returns 400 `realm_scope_unsupported`.


### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `since` | query | integer | No | Unix-seconds lower bound; omit for all-time. A negative/non-numeric value is rejected 400. |
| `X-Hoody-Cwd` | header | string | No | Per-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-Dir` | header | string | No | Per-request `--config-dir` override selecting which on-disk `.hoody` install a stateless read/write resolves (`HoodyPaths`). |
| `X-Hoody-Container` | header | string | No | Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension. |
| `X-Hoody-Realm` | header | string | No | Per-request realm selector: `global` or a 24-hex id (also accepted as `?realm=`). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes. |
| `realm` | query | string | No | Per-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



```json
{
  "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
    }
  ]
}
```


```json
{
  "code": "bad_request",
  "message": "invalid since value"
}
```

| 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 realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope. | Omit the realm header on this route, or open a session to scope by realm. |


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

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `forbidden` | Forbidden (not via the Hoody proxy) | Forbidden — the request did not reach the service through the public endpoint. | Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly. |


```json
{
  "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. |


```json
{
  "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. |



### SDK Usage

```ts
await client.agent.statistics.usageByModel()
```

With a `since` filter:

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