Skip to content
Run

Get Run Credits

Retrieve the per-function credit breakdown for a completed run

The v1 API, for batchesSquids, tasks and runs: many calls on a schedule, delivered where you work. For one call that answers in seconds, use the API v2.
GEThttps://api.lobstr.io/v1/runs/{run_hash}/credits

Returns a detailed credit breakdown for a single run, showing how credits were spent across base scraping and any enrichment functions (e.g. phone numbers, email extraction, images). Use this to understand the cost composition of a run and identify which functions drive the most spend.

Headers

Authorizationstringheaderrequired

Your API authentication token. Value: Token YOUR_API_KEY

Path Parameters

run_hashstringpathrequired

The unique identifier (hash) of the run. Example: 0393be3ea6f74986906153df1c3f9894

Response Fields

run_idstring

The hash ID of the run. Example: "0393be3ea6f74986906153df1c3f9894"

total_creditsfloat

Total credits consumed by the run. Example: 116

total_resultsinteger

Total number of results collected in the run. Example: 20

breakdownarray

List of per-function credit entries, sorted by credits descending.

Show breakdown item
functionstring

Internal function name. "base" represents the core scraping step. Enrichment functions (e.g. "get_phone_numbers", "extract_emails_from_website") appear as separate entries. "filters" is a virtual entry that groups all active filter costs.

creditsfloat

Credits charged for this function. Example: 80

attemptsinteger

Number of results this function ran on. For the virtual "filters" entry this is 0.

ratesobject

Credit rates for the run's squid.

Show rates fields
credits_per_rowfloat

Base cost per result. Example: 4

[function_name]float

Cost per result for each enrichment function, keyed by function name. Example: "get_phone_numbers": 6

function_colorsobject

Display color palette for each function, used by the dashboard UI.

Show function_colors item
bg_colorstring

Background color hex. Example: "#EAFBF3"

txt_colorstring

Text / foreground color hex. Example: "#0F9F5F"

base_function_labelstring | null

Human-readable display name for the base scraping step, derived from the squid's configuration. Example: "Export Listings (No Phone)". null if the squid has no labelled main function.

filter_breakdownarray

Per-filter credit detail when the squid charges for active filters (e.g. geo match, category match). Empty array if no filter costs apply.

Show filter_breakdown item
namestring

Internal filter parameter name. Example: "geo_match"

displaystring

Human-readable filter name shown in the UI. Example: "Geo Match"

ratefloat

Credits charged per result for this filter. Example: 1

creditsfloat

Total credits charged for this filter in the run. Example: 20

Credits are only charged for results that were successfully collected. Results discarded by filters (e.g. closed businesses, website filter, geo/category mismatch) are not billed.

Code Examples

curl -X GET "https://api.lobstr.io/v1/runs/0393be3ea6f74986906153df1c3f9894/credits" \
  -H "Authorization: Token YOUR_API_KEY"

Response

200
{
  "run_id": "0393be3ea6f74986906153df1c3f9894",
  "total_credits": 116,
  "total_results": 20,
  "breakdown": [
    {
      "function": "base",
      "credits": 80,
      "attempts": 20
    },
    {
      "function": "get_phone_numbers",
      "credits": 36,
      "attempts": 20
    }
  ],
  "rates": {
    "credits_per_row": 4,
    "get_phone_numbers": 6
  },
  "function_colors": {
    "Export Listings (No Phone)": {
      "bg_color": "#EAFBF3",
      "txt_color": "#0F9F5F"
    },
    "get_phone_numbers": {
      "bg_color": "#EEF2F7",
      "txt_color": "#62748A"
    }
  },
  "base_function_label": "Export Listings (No Phone)",
  "filter_breakdown": []
}
404
{
  "detail": "Run not found."
}