03 — credits
Credits & billing
One successful search costs one credit and returns one page of results. Credits never expire, and a request that fails costs zero.
The model
You buy credits in packs from the console; every pack shows its effective price per 1,000 searches. Rates start at $2.50 per 1,000 and drop to $1.00 per 1,000 on the largest packs, with a $50 minimum purchase. Custom amounts get the rate of the highest pack they reach. There are no subscriptions, no monthly minimums, and no expiry. A credit sits in your balance until a search spends it.
| field | type | default | description |
|---|---|---|---|
| 200 ok | outcome | −1 | A parsed SERP. The only outcome that costs anything. |
| 4xx request error | outcome | −0 | Bad key, bad parameters, or insufficient balance. Rejected before any work happens. |
| 502 search_failed | outcome | −0 | The search couldn't be completed. Our fault, never your credit. |
| 503 search_unavailable | outcome | −0 | Google didn't serve a usable results page. Retry; you weren't charged. |
Balance in the headers
Every response, success or failure, reports what it cost and what's left, so you never need a separate balance call in your request path:
HTTP/2 200
content-type: application/json
x-serpix-credits-charged: 1
x-serpix-credits-remaining: 24999| field | type | default | description |
|---|---|---|---|
| X-Serpix-Credits-Charged | integer | — | Credits this request consumed: 1 on success, 0 on any failure. |
| X-Serpix-Credits-Remaining | integer | — | Your organization's balance after this request. |
Running out
When the balance can't cover a search, the request is rejected up front with 402. Nothing is fetched and nothing is charged:
HTTP/2 402
content-type: application/json
{ "detail": "insufficient credits" }Top up from the console's billing page. Purchases land in the balance the moment payment completes.