---
title: "Get Agent Desk Usage"
method: GET
path: "/api/domains/{domain_id}/agent-desk/usage"
tags: ["agent_desk"]
---

# Get Agent Desk Usage

`GET /api/domains/{domain_id}/agent-desk/usage`

## Request

- Base URL: `https://api-v1.unusual.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api-v1.unusual.ai/api/domains/{domain_id}/agent-desk/usage`
- Auth: OAuth 2
  - Password
  - Token URL: `/auth/login`

The desk's own usage against its entitlements.

Thin by design: every number comes from
``usage_limits.get_desk_entitlements_snapshot``, which is also what the answer
path's 429 gate folds its limit from — so the tile the customer reads and the
ceiling the gate enforces cannot drift apart.

## Path parameters

- `domain_id` string, required

## Headers

- `x-view-as` string, nullable

## Response `200`

Successful Response

- DeskUsageOut: AGENTDESK-P2(PR-C): the customer-visible usage readout for the desk Overview. Two numbers plus the honesty around them: * ``answers_today`` / ``answers_limit`` → "N of X answers today". Both may be ``None`` and the two ``None``s mean DIFFERENT things, which is why they are separate fields rather than a formatted string: a ``None`` limit means uncapped (render "N answers today", no ratio), a ``None`` usage means we could not read the counter (render "—", never 0). * ``published_pages`` / ``published_pages_included`` → the billable count and what the plan includes. This resource is never enforced; the included figure is an allowance, and overage bills as subscription quantity. * ``answers_period`` → the period-scoped bundle (Option C). ``None`` when no bundle applies to this plan OR the read failed — the UI omits the line rather than inventing a number. * ``can_pick_subdomain`` → whether the plan entitles the customer to configure the desk's exact subdomain label (Growth/Scale; Starter stays on the ``"agents"`` default). Read through ``usage_limits.plan_allows_custom_subdomain``, the same reader the hosting routes' 403 gate uses — so the picker the UI shows and the write the server accepts cannot disagree. Defaults False: an unreadable plan row renders the upsell line, never a control the save would then refuse.
  - `answers_today` integer, nullable, required
  - `answers_limit` integer, nullable, required
  - `answers_limit_source` string, required
  - `answers_reset_in_seconds` integer, required
  - `published_pages` integer, required
  - `published_pages_included` integer, nullable, required
  - `plan_name` string, nullable, required
  - `answers_period` DeskPeriodBundleOut: The bundle readout — "N of M credits this period", plus whether the serving gate has paused the desk. Mirrors ``billing.period_bundle_usage``'s dict field-for-field, because this is the owner-facing half of that gate: the public refusal deliberately says nothing about bundles (see ``paywall.raise_if_gated``), so this surface is where "your desk is paused" is actually said. The unit moved from answers to CREDITS with the metered lane (2026-08-16); the credit fields are optional so a cached older payload shape still parses. (The per-model spend page and its ``/spend`` route were removed 2026-10-15; this is the only readout.)
    - `used` integer, required
    - `bundle` integer, required
    - `period_start` string, required
    - `period_source` string, required
    - `exhausted` boolean, required
    - `unit` string, nullable
    - `overage_limit` integer, nullable
    - `overage_used` integer, nullable
    - `free` boolean, nullable
  - `can_pick_subdomain` boolean
  - `ingested_sources` integer
  - `ingested_sources_included` integer, nullable
  - `free_plan` boolean

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/unusual/apis/dashboard-server.md) - [All operations](https://skmtc.dev/unusual/apis/dashboard-server/llms.txt) - [OpenAPI document](https://skmtc.dev/unusual/apis/dashboard-server/revisions/89f716930ead?raw)