# GET /v1/profiles/{profileSlug}/token-usage

Read the frozen profile-wide token-usage series when its public API grant is enabled.

Base URL: https://directory.seorak.app. No key, no account, and no headers.

## Parameters

- `profileSlug` (path, required) The public profile slug. 0 to 63 characters, matching `^[a-z0-9]+(?:-[a-z0-9]+)*$`.

## Response 200

- `apiVersion` (string) Always v1 on this surface.
- `publicationVersion` (integer) Monotonic version of the publication behind this projection.
- `publishedAt` (string) When the publication first became public.
- `updatedAt` (string) When the current projection was written.
- `revokedAt` (string | null) Always null on a public read; a revoked item is not served.
- `surface` (string) Which grant produced this projection. Each surface is a separate decision. One of: web, api, mcp.
- `profileSlug` (string) The public profile slug.
- `projectSlug` (string | null) Null for a profile-wide series; set for a project-scoped embed.
- `rangeDays` (integer) Frozen window length in days. One of: 30, 90.
- `period` (object) Window the series covers.
  - `from` (string) First day in range, as a calendar date.
  - `through` (string) Last day in range, inclusive.
- `fields` (object) Only the frozen token-usage fields this surface's allowlist selected.
  - `series` (object, optional) Frozen day-by-day token series. Readers never recompute it from private history.
    - `days` (object[]) One entry per day in the period.
      - `date` (string) The calendar day the tokens were observed on.
      - `byAgent` (object) Input+output tokens for each published agent that day. Absent keys were not measured.
        - `claude-code` (integer, optional) Claude Code tokens that day.
        - `codex` (integer, optional) Codex tokens that day.
      - `total` (integer | null) Sum of byAgent for that day, or null when coverage cannot support a total.
      - `coverage` (string) How much of the day the record can account for. One of: complete, partial, unavailable.
      - `availability` (object) Why a day could not be claimed, when it could not.
        - `state` (string) Whether the source could support the claim at all. One of: available, partial, unavailable.
        - `reason` (string | null) Null when fully available; otherwise a stable capability gap. Never treat a gap as a zero. One of: not-captured, not-retained, not-yet-computed, outside-credential-restriction, temporarily-unavailable, result-limit.
    - `generatedAt` (string) When the series was frozen.
    - `freshness` (object) Age of the frozen series.
      - `state` (string) Freshness travels with the frozen claim rather than being inferred by the reader. One of: fresh, stale, revalidating.
      - `generatedAt` (string) When this projection was derived.
      - `dataThrough` (string | null) Latest source observation included, or null for an honest-empty result.
      - `staleAt` (string) Boundary after which a caller must describe the projection as stale.
  - `totals` (object, optional) Period sum across the frozen window, with availability and coverage.
    - `total` (integer | null) Period total, or null when the sum cannot be claimed.
    - `byAgent` (object) Period totals by agent.
      - `claude-code` (integer, optional) Claude Code period total.
      - `codex` (integer, optional) Codex period total.
    - `availability` (object) Whether the period total could be supported.
      - `state` (string) Whether the source could support the claim at all. One of: available, partial, unavailable.
      - `reason` (string | null) Null when fully available; otherwise a stable capability gap. Never treat a gap as a zero. One of: not-captured, not-retained, not-yet-computed, outside-credential-restriction, temporarily-unavailable, result-limit.
    - `sampleSize` (integer) Number of days that contributed a measured total.
    - `coverage` (object) The window the total describes.
      - `period` (object) Measured window.
        - `from` (string) First day in range, as a calendar date.
        - `through` (string) Last day in range, inclusive.
      - `complete` (boolean) False means the window has gaps, so the value is a floor.

## Example

```sh
curl -sS 'https://directory.seorak.app/v1/profiles/ada/token-usage'
```

```json
{
  "apiVersion": "v1",
  "publicationVersion": 7,
  "publishedAt": "2026-06-14T09:00:00.000Z",
  "updatedAt": "2026-07-30T16:20:00.000Z",
  "revokedAt": null,
  "surface": "api",
  "profileSlug": "ada",
  "projectSlug": null,
  "rangeDays": 30,
  "period": {
    "from": "2026-07-02",
    "through": "2026-07-31"
  },
  "fields": {
    "series": {
      "days": [
        {
          "date": "2026-07-30",
          "byAgent": {
            "claude-code": 120000,
            "codex": 40000
          },
          "total": 160000,
          "coverage": "complete",
          "availability": {
            "state": "available",
            "reason": null
          }
        },
        {
          "date": "2026-07-31",
          "byAgent": {},
          "total": null,
          "coverage": "unavailable",
          "availability": {
            "state": "unavailable",
            "reason": "not-captured"
          }
        }
      ],
      "generatedAt": "2026-08-01T06:00:00.000Z",
      "freshness": {
        "state": "fresh",
        "generatedAt": "2026-08-01T06:00:00.000Z",
        "dataThrough": "2026-07-31T23:59:59.000Z",
        "staleAt": "2026-08-08T06:00:00.000Z"
      }
    },
    "totals": {
      "total": 160000,
      "byAgent": {
        "claude-code": 120000,
        "codex": 40000
      },
      "availability": {
        "state": "available",
        "reason": null
      },
      "sampleSize": 1,
      "coverage": {
        "period": {
          "from": "2026-07-02",
          "through": "2026-07-31"
        },
        "complete": false
      }
    }
  }
}
```

## More

- Surface overview: https://seorak.app/docs/api.md
- Whole reference in one document: https://seorak.app/llms-full.txt
- Machine-readable HTTP schema: https://seorak.app/openapi.json

---

Source: https://seorak.app/docs/api/tokenUsage
This document: https://seorak.app/docs/api/tokenUsage.md