Credits & errors

Buying credits

Packs from $1, the bonus on larger amounts, what happens when you run out, top-up links and automatic top-up.

Credits are prepaid: there is no subscription, and you buy more when you need them. A metered call your balance cannot fund fails with 402 credits.insufficient, and buying credits is the only fix. This page covers how buying works, what that error carries, how an integration hands a person a link to pay, and automatic top-up.

Buying in the dashboard#

Workspace admins buy credits on the dashboard's Billing page, by card, in US dollars. A dollar buys 100 credits, and any whole-dollar amount from $1 to $1,000 can be bought.

Larger amounts include extra credits. The bonus applies to the whole amount; bonuses do not stack.

Amount	Bonus	Credits per dollar
$1 to $24	none	100
$25 to $99	10%	110
$100 to $1,000	12%	112

The four packs on the Billing page are starting points, not limits: each opens the purchase dialog at its amount, and you can change the amount there.

Pack	Amount	Credits
Small	$1	100
Medium	$25	2,750
Large	$100	11,200
Scale	$1,000	112,000

For example, $37 buys 4,070 credits and $150 buys 16,800. The server works out the bonus and the credits from the amount; what the dialog shows is a preview. For more than $1,000, contact sales.

A new workspace starts with 1,000 free credits, granted once at signup.

Credit expiry

Free credits expire 90 days after they are granted. That covers the signup grant, referral credits and promotional credits. Credits you buy never expire.

`402 credits.insufficient`#

When the allocation cannot fund an action:

{
  "type": "https://dashboard.sproutsdata.ai/errors/credits-insufficient",
  "title": "Insufficient credits",
  "status": 402,
  "code": "credits.insufficient",
  "detail": "This action costs 0.595 credits; 0.25 available.",
  "instance": "/v1/search",
  "request_id": "bd22794d0c5c06f1d3e7045e3c0e32ab",
  "extra": { "available": 0.25, "required": 0.595, "action_type": "dsp.search.auto" }
}

extra always carries available, required, and action_type. available and required are credits, to at most three decimals. When your tenant holds general Sprouts credits that cannot fund this platform, it may also carry unrestricted_not_usable — show both numbers: "0 data-platform credits (you have N elsewhere)" is a different message from "you are out of credits", and only the first is true.

Handing a person a link to buy credits#

Your integration or agent runs on an API key, and the wallet is empty. A key can never buy credits, but it can ask a person to.

Create a top-up link

POST /v1/billing/top-up/intents takes no body and returns a dashboard link:

{
  "topup_id": "…",
  "url": "https://dashboard.sproutsdata.ai/billing/top-up?t=…",
  "expires_at": "2026-10-01T12:15:00Z",
  "meta": { "request_id": "…", "environment": "live", "as_of": "…", "credential": "api_key" }
}

There is no amount, platform or tenant to set: the person chooses the amount in the browser, and the tenant comes from your credential.

Hand the link to a person
They open url, sign in, and pay. The link lasts 15 minutes (expires_at). The purchase itself still needs a signed-in dashboard session and billing permission.
topup_id is only a correlation id. It authorises nothing, so it is safe to show in a chat or a log.
Poll until the payment lands
Poll GET /v1/billing/top-up/intents/{topup_id}. It is safe to call every few seconds. status is pending until the purchase lands, then completed with credits_added (and order_id).

Both top-up routes are free and accept any credential of the workspace with dsp.usage.read, the same as GET /v1/credits.

After the link expires, and for an id that belongs to another workspace, the status route returns 404 payment.topup_not_found, and you start a new top-up.
Environments without a dashboard to send people to return 501 request.unsupported from the POST.

The Sprouts MCP server uses this flow when it runs out of credits.

Automatic top-up#

Workspace admins can also have the dashboard buy credits automatically. Setting up the rule needs the same billing permission as buying credits by hand.

Open Billing
In the dashboard, go to Billing and choose Set up automatic top-up.
Fill in the four values
- The credit balance to top up below (only credits spendable on this platform count).
- How much to buy, in USD: a whole-dollar amount from $1 to $1,000. The same bonus applies as to a purchase by hand.
- Which saved card to charge.
- A daily limit, in USD. It must cover at least one top-up.

The rule never switches on with default values: it needs a threshold, an amount and a card. It charges only the card it names, never whichever card was used last. A colleague's manual purchase therefore never changes which card the rule charges, and removing that card stops automatic top-up.