---
title: "Update Agent Desk Overage"
method: PATCH
path: "/api/domains/{domain_id}/agent-desk/usage/overage"
tags: ["agent_desk"]
---

# Update Agent Desk Overage

`PATCH /api/domains/{domain_id}/agent-desk/usage/overage`

## 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/overage`
- Auth: OAuth 2
  - Password
  - Token URL: `/auth/login`

Set the payer org's overage credit allowance — the customer's opt-in to
pay per credit past the plan's bundle (Billing page). Off by default.

Money fails closed, so three refusals guard the write:

* ``get_domain`` alone admits AGENCY-GRANT holders, and a grant never
  confers billing mutation (models.py) — the caller must BELONG to the
  domain's org (or be staff), the binding payments.py uses;
* a domain whose bills land on ANOTHER org (agency billing) cannot move
  the payer's allowance;
* a plan row with no metered Stripe price cannot ENABLE overage: the gate
  would serve credits nothing can bill. Disabling (0/null) always works.

Takes effect on the next ask: the serving gate reads the org row live.

## Path parameters

- `domain_id` string, required

## Headers

- `x-view-as` string, nullable

## Request body

- DeskOverageUpdate
  - `overage_credit_limit` integer, 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)