Credits & errors

Usage history

Audit every billable run a credential made, re-read a past search's results for free, and chart requests and credits per day.

Every metered call is recorded as a run: what it asked, when, what it cost and how it went. Usage history reads those runs back. All three routes are free to call and require dsp.usage.read.

Use usage history when you need to know what happened: which requests a key made, what each one cost, or what a past search returned. To check what you can still spend, use Balance and spend instead.

Use cases#

Audit what a key ran

A service spent more than expected. You get every run it made, newest first, each with its action, outcome and cost.

Re-read a past search

You need yesterday's results again. You get the original request and its first page of results, stored and free to read.

Chart usage per day

You report on usage or reliability. You get requests, outcomes and credits per day per action, already bucketed.

Each tab shows the request to send and the outcome you hold when it returns.

List the runs for one window. Repeat action_type to include several actions; leave it out for everything:

curl "https://api.sproutsdata.ai/v1/usage/history?action_type=dsp.search.fast&action_type=dsp.search.auto&from=2026-10-01T00:00:00Z&limit=25" \
  -H "X-API-Key: $SPROUTS_API_KEY"

Outcome: a page of runs, newest first, each with its id, occurred_at, action_type, status, query, result_count and credits_charged. Page with next_cursor, as on every list route.

How it works#

  • Scope: all three routes require dsp.usage.read.
  • Billing: free. Reading history, a run's detail or its snapshot never costs anything.
  • Retention: runs are kept for 90 days. Snapshots are kept for 30 days.

Whose runs you see

The answer follows the credential you call with:

CredentialSees
API keyThe runs that key made
Dashboard sessionThe signed-in user's runs, plus the runs of every API key that user created, including revoked keys

Other members' runs are never included.

Reading a run

  • status is pending from the moment a run starts costing something until it finishes, then ok or failed. A run that stays pending far longer than any request could take is reported as failed, with an error_code that says why: incomplete for a request that never finished, or unsettled for an agent run that nobody read before its credit hold expired.
  • credits_charged is what the ledger charged, so history always agrees with your bill. It reads 0 for rows already paid for, such as a cursor sent again or a retry with the same Idempotency-Key.
  • query is what makes a run recognisable: the search text, the anchors of a look-alike search, the ids of a record lookup, or the company pair of a relationship question.
  • action_type is one of the dsp.* actions listed under Credits & usage, and actor_type says whether a user session or an api_key made the run.

Each charged page of a search is its own run.

Snapshots

Only a search's first page is stored. When snapshot is null, snapshot_state says why:

snapshot_stateMeaning
presentThe snapshot is included
expiredThe run is older than 30 days
omitted_too_largeThe page was too large to store
continuationThe run is a later page of a search
absentThere was nothing to store: a pending or failed run, or an agent run

Agent runs never store a snapshot, because their results stay free to re-read through GET /v1/agents/runs/{run_id}/results.

Errors

Everything in the errors guide applies. A run id that is unknown, expired or belongs to someone else returns 404 history.not_found, the same answer in all three cases.

Best practices#

  • Give each service its own key. History is per credential, so separate keys make every run attributable.
  • Read the snapshot before re-running a search. It is free, and a re-run is a new, billed search.
  • Use metrics for charts and history for investigation. Metrics are already bucketed by day; history is the per-run detail behind them.
  • Store anything you need beyond 30 days. Snapshots expire after 30 days, and runs after 90.

For every field and parameter, see the Usage history API reference.