Pricing and credits

Every call to /api/v1 spends request credits from your organization's balance. You buy them yourself in API usage and keys. There is no contract and no call to book.

How credits work

• Starter credits. Every organization gets 100 free starter credits once. Backwork adds them the first time the organization's balance is read, for example when you open API usage and keys or make your first call. They never expire.
• Credits pack. $20 for 1,000 requests, paid once. Purchased credits never expire. The pack has no overage: when the balance cannot cover a call, the call is refused.
• Build and Scale. A monthly allowance that resets each billing period; unused monthly requests do not carry over. When the allowance and any purchased credits are spent, further requests bill as overage instead of being refused. An organization has one monthly pack at a time; switch or cancel it in Billing.

Each call spends the monthly allowance first, then purchased and starter credits, then overage.

The tables below are generated from the prices, limits, and request costs the API enforces.

Packs and limits

Every organization starts with 100 free starter credits, granted once; they never expire. Every API key in an organization draws on one balance of request credits and one sliding one-minute rate-limit window. A monthly allowance is spent before purchased Credits, and purchased Credits never expire. On Build and Scale, requests past the allowance bill as overage at $0.002 per request. With only Credits, a call the balance cannot cover returns 402 BILLING_CREDITS_EXHAUSTED. Some endpoints count as more than one request, for both credits and the rate limit; the rest count as one.

Request costs

A request's cost counts against the per-minute rate limit too: a call that counts as 6 spends 6 credits and uses 6 of the minute's limit. The cost does not depend on how many results come back.

These requests spend nothing:

• a request refused with 402 or 429;
• a retry that returns the stored response of an idempotent request (the response has Idempotent-Replayed: true);
• GET /api/v1/prior-auth/research/{id}, which polls a research task you already paid for.

When credits run out

Before running a call, the API checks that the balance covers its cost. If it does not, and the organization has no active monthly pack to bill overage, the API answers 402 and does not run the call:

{
  "success": false,
  "error": {
    "code": "BILLING_CREDITS_EXHAUSTED",
    "message": "Your organization has no request credits left for this call",
    "hint": "details.requests_required is this call's cost and details.requests_available is the balance. Retry once the balance covers the call. An organization admin can manage the plan and usage in the Backwork dashboard at https://backworkhealth.com/api-usage",
    "docUrl": "https://backworkhealth.com/docs/errors#billing-credits-exhausted",
    "retryable": false,
    "details": { "requests_required": 6, "requests_available": 4 }
  },
  "meta": { "request_id": "req_...", "timestamp": "..." }
}

• retryable is false: sending the same request again fails the same way until the balance changes. Do not retry it in a loop.
• details.requests_required is the call's cost and details.requests_available is what is left. A call can be refused while some credits remain, when it costs more than the balance. Cheaper calls still work.
• After you buy credits, send the request again. It runs normally.
• A monthly pack whose payment is past due does not bill overage. Its calls are refused the same way once the allowance and credits are spent. Update the card in Billing.

The error's docUrl points to the BILLING_CREDITS_EXHAUSTED entry on the errors page, which links back here.

Buy credits and check the balance

Open API usage and keys:

• Request balance shows the requests available now, the monthly allowance left and when it resets, and the purchased and starter credits.
• Buy requests opens Stripe Checkout for a Credits pack or a monthly pack. Your balance updates a few seconds after the payment.
• The activity list shows recent grants, purchases, and the requests each endpoint spent.

Only organization owners and admins can buy packs and create keys. Other members can see the balance.

No API endpoint returns the balance. In code, read details.requests_available from a 402, and watch the X-RateLimit-* headers for the per-minute limit.

MCP and agent tools

The MCP server calls the same /api/v1 endpoints with your OAuth token or API key, so its tool calls spend the same credits and count against the same rate limit. One tool call can make several API requests. Agent tool calls cost what the table above lists for POST /api/v1/agent/tools/{tool}.

Webhooks and the Scale SLA

Scale includes webhook endpoints (/api/v1/webhooks). Backwork currently sends only compliance.acknowledged events to them; policy-change events are not delivered.

Scale also carries the published SLA. Credits and Build carry none.

Last updated on