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

# Call billing.plan_status

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

## Request

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

Say what plan the account is on and what is left — 'what plan am I on?', 'how many credits do I have left?', 'when does my next bill go out?'.  Read what plan this account is on, how many credits it has left, and its recent charges. Say the figures back exactly as given — never work one out or recall one. Every timestamp is ISO-8601 UTC: convert it into the `display_time_zone` this returns before you name a date, or you will say a different day than their billing page shows. You cannot change any of it: plan changes, top-ups and cards are theirs to do on Settings → Billing. Not for where the credits went — that is `billing.usage_summary`.

## 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
    - `plan_key` string, required
    - `plan_name` string, required
    - `price_cents` integer, required
    - `interval` string, nullable, required
    - `subscription_status` string, nullable, required
    - `subscribed` boolean, required
    - `renews_at` string, nullable, required
    - `credit_balance` number, required
    - `monthly_allotment` number, required
    - `out_of_credits` boolean, required
    - `auto_top_up_enabled` boolean, required
    - `auto_top_up_disabled_after_failure` boolean, required
    - `card_on_file` boolean, required
    - `non_card_method_type` string, nullable, required
    - `receipts` object[], required
      - `paid_at` string, required
      - `description` string, required
      - `amount_minor_units` integer, required
      - `currency` string, required
    - `account_visible` boolean, required
    - `no_charge` boolean, required
    - `partial_reads` string[], required
    - `display_time_zone` string, nullable, 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/6d82fb124064?raw)