Balance and spend

Both routes are free to call and need dsp.usage.read. Use the balance before a batch job, and per-key spend to see which service is spending.

GET /v1/credits — balance#

Free; requires dsp.usage.read. Answers for the tenant, so either a key or a dashboard session can ask.

curl https://api.sproutsdata.ai/v1/credits \
  -H "X-API-Key: $SPROUTS_API_KEY"

{
  "platform": "dsp",
  "scope": "platform",
  "allocated": { "granted": 1000, "remaining": 993.3, "reserved": 0, "expires_at": "2026-09-11T18:18:24Z" },
  "shared": { "remaining": 624 },
  "spendable": 993.3,
  "as_of": "2026-08-12T19:51:31Z",
  "meta": { "request_id": "...", "environment": "live", "as_of": "...", "credential": "api_key" }
}

• spendable is the headline — the only number that predicts whether the next charge will succeed. Every credit figure is a number to at most three decimal places.
• allocated — credits ring-fenced for the data platform: granted, remaining, reserved (held by agent runs in flight), and expires_at. Free credits (the signup grant, referral and promotional credits) expire 90 days after they are granted; credits you buy never expire.
• shared — the tenant's unrestricted credits. Reported but not spendable here: the platform is hard-capped to its own allocation, so never render allocated.remaining + shared.remaining. It exists so an empty allocation beside a healthy shared balance reads as "move credits across", not as an empty account.
• scope: "tenant_wide_fallback" is a degraded shape (billing service not yet upgraded): allocated and shared are null and only spendable is meaningful.

GET /v1/keys/usage — per-key spend#

Free; requires dsp.usage.read.

curl "https://api.sproutsdata.ai/v1/keys/usage?granularity=day&from=2026-07-15T00:00:00Z&to=2026-08-14T00:00:00Z" \
  -H "X-API-Key: $SPROUTS_API_KEY"

{
  "key_id": "ak_83a0679e1e394a69910026a34b6b8b1a",
  "period_from": "2026-07-15T00:00:00Z",
  "period_to": "2026-08-14T00:00:00Z",
  "granularity": "day",
  "total_requests": 412,
  "total_credits": 268.415,
  "buckets": [
    { "period_start": "2026-08-13T00:00:00Z", "action_type": "dsp.search.fast", "requests": 31, "credits": 15.5 }
  ],
  "meta": { "request_id": "...", "environment": "live", "as_of": "...", "credential": "api_key" }
}

total_credits is what the key was charged, in credits to at most three decimals. Add credit figures as whole thousandths (multiply by 1,000 and round) if you sum them yourself, so binary floating point cannot drift.

For the individual runs behind these numbers — what each one asked, what it cost, and a free replayable snapshot of its results — see Usage history.