Credits and usage

Unif bills in credits, and the unit is a verified hit — one row that a source actually returned and that passed verification. That follows directly from the waterfall. A request runs down the cascade until something verifies; the steps that missed cost nothing, and the steps never reached cost nothing. You are charged once, for the answer. Two consequences worth internalizing:

A request is not a unit. Paging with limit=100 costs exactly what paging with limit=25 does, because the cost is in the rows, not the calls.
A miss is free. A search matching nothing, an enrichment that resolves not_found, a cascade that exhausts without verifying — all zero.

This page covers the consumption model — how many credits a call consumes. Plan sizes and pricing live in your dashboard at app.unif.dev.

What costs what

Call	Cost
`GET /me`, `/channels`, `/coverage`, `/usage`	Free
List, tracker and webhook management	Free
`POST /*/search`	1 credit per verified row returned
`GET /{entity}/{id}`	1 credit
`GET /{entity}/{id}/timeseries`	1 credit per bucket returned
`GET /lists/{id}/items`	1 credit per row returned
`POST /resolve`	1 credit per input resolved
`POST /enrich`	2 credits per row, or 1 with `fields` set
Job — `enrich` or `search`	Same per-row rate as the synchronous call
Job — `export`	1 credit per row exported
Tracker cycle	1 credit per entity checked

Three rules follow from this, and they cover most of what you need to know:

You pay for hits

Cascade steps that miss, fail verification, or are never reached are all free. Exploratory queries are cheap to get wrong.

Rows, not requests

Page size does not change cost. Always use limit=100.

Narrow fields, lower rate

Setting fields on an enrich call halves the per-row cost.

A deep cascade is not more expensive than a shallow one. If a row is answered at step 05 rather than step 01 you pay the same single credit — the cost of breadth is carried by Unif, not passed through per attempt.

Reading the cost of a call

Every billable response carries the cost in its headers:

X-Unif-Credits-Charged: 25
X-Unif-Credits-Remaining: 48210

Batch endpoints also report it in the body, which is easier to log:

{
  "object": "enrich_response",
  "credits_charged": 47,
  "data": [ /* … */ ]
}

Log X-Unif-Credits-Charged next to X-Request-Id on every call. When usage jumps, the answer is already in your logs instead of requiring a reconstruction.

The ledger

GET /v1/usage is the balance; GET /v1/usage/events is the itemized ledger.

curl "https://api.unif.dev/v1/usage/events?start=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer $UNIF_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "ue_01k3m9x7v2q8r4t6y0b1n5d7fa",
      "object": "usage_event",
      "endpoint": "POST /products/search",
      "rows": 100,
      "credits": 100,
      "request_id": "req_01k3m9x7v2q8r4t6y0b1n5d7fa",
      "created_at": "2026-09-15T02:14:08Z"
    }
  ]
}

Every event carries its request_id, so a surprising line in the ledger traces back to the exact call that produced it — and to your own log line for it.

from collections import Counter

by_endpoint = Counter()
for event in paginate(session, ".../usage/events", params={"start": month_start}):
    by_endpoint[event["endpoint"]] += event["credits"]

for endpoint, credits in by_endpoint.most_common(10):
    print(f"{credits:>10,}  {endpoint}")

Issue a separate API key per service. The ledger then attributes spend by service without any work on your side — see Authentication.

Spending less

Filter before you page

The largest avoidable cost is paging through a broad result set and discarding most of it client-side. A revenue floor or a tighter category turns 1,000 charged rows into 80.

Set fields on enrichment

fields halves the per-row rate and makes meta.completeness meaningful. There is no reason to request a full record you do not read.

Store IDs, do not re-resolve

Resolving the same URL every night charges for identity you already established. Store the shp_… ID once — see Identifiers.

Prefer trackers to re-reading lists

A tracker charges per entity checked, the same as reading the list — but it only wakes your systems when something crossed a threshold, and it will not silently keep running against a list nobody looks at.

Delete trackers you stopped reading

A daily tracker over 500 entities is 15,000 credits a month whether or not anyone acts on it. This is the most common source of unexplained spend.

Develop against the sandbox

Sandbox keys return fixture data and cost nothing. Integration tests should never touch live credits.

Running out

When a workspace exhausts its credits, billable calls return 402 with insufficient_credits. Free endpoints keep working, so GET /usage still answers and health checks stay green.

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "This request costs 25 credits and 4 remain in the current period.",
    "request_id": "req_01k3m9x7v2q8r4t6y0b1n5d7fa"
  }
}

402 is not retryable. Retrying burns rate limit and changes nothing until credits are added or the period rolls over. Alert on it instead — and alert on credits_remaining falling below a threshold, well before it reaches zero.

Workspaces with overage enabled continue past the included allowance and are billed for the difference. overage_allowed on GET /usage tells you which mode you are in.

Getting started

Core concepts

Workflows

Guides

Platform

Release notes

Credits and usage

What costs what

You pay for hits

Rows, not requests

Narrow fields, lower rate

Reading the cost of a call

The ledger

Spending less

Running out

​What costs what

You pay for hits

Rows, not requests

Narrow fields, lower rate

​Reading the cost of a call

​The ledger

​Spending less

​Running out

What costs what

Reading the cost of a call

The ledger

Spending less

Running out