REST API: billing

These endpoints are read-only. Use them to build your own usage dashboards or alerts, or to gate a workflow before it hits a plan limit. GET /billing/subscription returns the organization's current plan and subscription state. GET /billing/usage returns the credit balance and usage flags that drive in-product warnings. GET /billing/credit-history returns the transaction history behind that balance, so you can reconcile consumption over time.

GET /billing/agent-limit and GET /billing/crawl-limit check the organization's current count against its plan's cap for agents and crawl pages. Call one before you create an agent or start a large crawl from an automated pipeline, so your integration fails with a clear plan-limit error instead of a partial, hard-to-clean-up operation.

None of these endpoints can change a plan, add a payment method, or trigger a purchase. Checkout, the billing portal, and auto-top-up remain dashboard-only actions. Do not build an integration that assumes it can act on the data these endpoints return; treat the response as informational.

These endpoints require a read-scoped key. An MCP client reaches the same data through the catalog, gated on the dedicated mcp:billing scope described in MCP scopes — not the general mcp:read scope other read tools use.

ChangesCopy Anchor Link

• 2026-09-24 — In GET /billing/credit-history, the published schema for amount and balanceAfter is a number, not an integer. Credits are fractional to 4 decimal places, and 1 credit is $0.02. The values in the response did not change. Regenerate a client that you generated from the old schema, because it can reject a real row such as 0.25.