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

# Call billing.usage_summary

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

## Request

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

Say where the account's credits went — 'where did my credits go?', 'what used up my balance this month?', 'which brand is spending the most?'.  Read one calendar month of credit consumption — the total spent, the split per workspace, and a tail of the itemized ledger. Use it before answering any 'where did my credits go' question rather than reasoning from memory. Ledger instants are ISO-8601 UTC — convert them into the `display_time_zone` this returns before you name a day. Not for the plan and balance today — that is `billing.plan_status`.

## Headers

- `x-request-id` string

## Request body

- object
  - `month` string: Which calendar month to summarize, as YYYY-MM. Leave it out for the current month. Never guess a month they did not name.

## 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
    - `month` string, required
    - `spent_credits` number, required
    - `workspace_rollup` object[], required
      - `workspace_id` string, nullable, required
      - `workspace_name` string, nullable, required
      - `credits` number, required
      - `event_count` integer, required
    - `recent_entries` object[], required
      - `occurred_at` string, required
      - `entry_kind` string, required
      - `activity_key` string, nullable, required
      - `workspace_name` string, nullable, required
      - `credits` number, required
    - `more_entries` boolean, 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)