---
title: "Call billing.budget_status"
method: POST
path: "/api/v1/tools/billing.budget_status"
tags: ["billing"]
---

# Call billing.budget_status

`POST /api/v1/tools/billing.budget_status`

## Request

- Base URL: `https://app.goosybear.ai`
- URL: `https://app.goosybear.ai/api/v1/tools/billing.budget_status`
- Auth: HTTP bearer

Read the account's own monthly budget and how much of it is spent, and every other spend cap's burn — 'how much of our budget have we used?', 'what's our monthly budget?', 'do we pause at the budget?', 'how close are we to our spend cap?'. `payer_budget` is the budget the account set for itself, in credits: this month's spend against it, whether reaching it emails the owners and admins (`notify`) or pauses work that needs credits (`pause`), and the percentages they are emailed at. Say the figures back exactly as given. If `payer_budget.unavailable` is true, say the budget could not be read; never report that as 'no budget', and never report an unavailable cap list as 'no limits'. The other caps are read-only here. Not for changing the budget — that is `billing.budget_set`; not for the credit balance — that is `billing.plan_status`.

## Headers

- `x-request-id` string

## Request body

- object

## Response `200`

The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.

- union
  - object: The tool ran and answered.
    - `ok` true, required
    - `payer_budget` object, required
      - `set` boolean, required
      - `budget_credits` number, nullable, required
      - `spent_credits` number, nullable, required
      - `percent_used` number, nullable, required
      - `at_budget` 'notify' | 'pause', nullable, required
      - `alert_percents` number[], required
      - `can_edit` boolean, required
      - `unavailable` boolean, required
    - `rows` object[], required
      - `key` string, required
      - `label` string, required
      - `unit` string, required
      - `window` string, required
      - `limit_value` number, required
      - `consumed` number, required
      - `percent_used` number, required
      - `enforcement` string, required
    - `unavailable` boolean, required
  - ToolRefusal: A call that was admitted and dispatched, and did not succeed.
    - `ok` false, required
    - `code` string, required: The typed reason — e.g. `workspace_ambiguous`, `invalid_arguments`, or the tool's own failure code.
    - `message` string, required: A sentence a person can act on.
    - `workspaces` string[]: On a workspace refusal: the slugs this key may pass as `workspace`.
    - `issues` object[]: On `invalid_arguments`: which fields failed, and why.
      - `path` string, required
      - `message` string, required
    - `path` string: On an authoring refusal: where in your call's input it points, e.g. `steps.<key>.params.<field>`.
    - `fix` string: On an authoring refusal: the change to your call that would pass.
    - `instruction` string: On an authoring refusal: what to do next with it.

## Other responses

- `400`: The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.
- `401`: No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.
- `403`: The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.
- `404`: No such tool. The body names no tool and is identical for every unrecognised name.
- `429`: Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.

---

[API](https://skmtc.dev/goosybear/apis/goosy-bear-api.md) · [All operations](https://skmtc.dev/goosybear/apis/goosy-bear-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goosybear/apis/goosy-bear-api/revisions/0e033701d3f7?raw)