Credits & pricing
Onekey charges in credits. Every endpoint has a flat price you can see before you call it. No monthly minimums, and credits never expire.
Price points#
Endpoints cost 1 to 8 credits. Most are 1, 2 or 5.
| Price | Cost | Typical endpoints |
|---|---|---|
| Standard | 1 credit | Simple lookups on open platforms, such as a profile or a package. |
| Advanced | 2, 3 or 5 credits | Lists and searches that need a paid data route, and hard-to-reach platforms. Searches on open platforms are often 1. |
| Other | 6 or 8 credits | A few endpoints with their own price when the work does not fit either. |
The exact price is always on the endpoint page and in the catalog.
When you are charged, and when you are not#
| Situation | Cost |
|---|---|
| Fresh fetch that succeeds | The endpoint price. |
| Answer served from cache (fresh or stale) | Free. (A cached response over 100 KB costs 0.2 credit, never more than the endpoint price.) |
Record not found (404) | Free (reserved, then refunded). |
Source failed or timed out (502) | Free (refunded). |
Invalid parameters (422) | Free (rejected before any charge). |
Bad key (401), rate limited (429) | Free. |
| An empty list from a search that succeeded | The endpoint price. It is a real answer. |
Each further page of a list (cursor) | The endpoint price per page (see Pagination). |
A replay for an Idempotency-Key you already used | Free (see Idempotency). |
Every response tells you what it cost in metadata.credits_charged. Check your balance any time, free, with GET /v1/account (or GET /v1/credits/balance). After a call that charged something, the X-Credits-Remaining header carries the new balance (see Rate limits & headers).
Your credit ledger#
GET /v1/credits/transactions returns every movement on your account's credits, newest first, with the balance after each row. It needs an API key, costs nothing, and counts as an ordinary request for the rate limit. Credits belong to the account, so every key of the account sees the same ledger; key_id says which key a spend came from.
curl "https://api.onekey.dev/v1/credits/transactions?limit=3" -H "x-api-key: YOUR_API_KEY"{
"success": true,
"data": [
{ "id": 412, "type": "settle", "credits": 0, "balance_after": 997, "description": "Unused part of a hold returned after a call", "ref": "9b1e...", "key_id": "key_abc", "created_at": "2026-10-02T09:15:01+00:00" },
{ "id": 411, "type": "reserve", "credits": -3, "balance_after": 997, "description": "Credits held while a request runs", "ref": "9b1e...", "key_id": "key_abc", "created_at": "2026-10-02T09:15:00+00:00" },
{ "id": 1, "type": "grant", "credits": 1000, "balance_after": 1000, "description": "Credits added (signup grant, pack purchase)", "ref": "signup", "key_id": null, "created_at": "2026-10-01T08:00:00+00:00" }
],
"pagination": { "next_cursor": "eyJ2Ijox...", "has_more": true, "page_size": 3 }
}A call is usually two rows: a reserve (the worst-case price is held) and then a settle or refund that hands back whatever was not kept, so the net of the pair is what the call cost. Types: grant (credits added), reserve, topup (a bigger hold), settle, refund, charge, hit (a charged cache hit) and clawback (a refunded or disputed payment). credits is signed: spends are negative.
| Parameter | Meaning |
|---|---|
limit | Rows per page, 1 to 100 (default 50). |
cursor | pagination.next_cursor from the previous page, sent back untouched with the same filters. |
type | Comma list of the types above. |
key_id | Only spend attributed to this key. |
from, to | ISO 8601 bounds (from inclusive, to exclusive). |
For one row per call with its endpoint and result, use the request log in the dashboard.
Credits never expire#
What you buy stays until you use it. 1,000 free credits cover the open-platform endpoints. Hard-to-reach platforms (X, TikTok, Instagram, Reddit, and others marked on their page) need a verified email and a purchased pack. Buy more in packs on the pricing page.
Cost examples#
- 100 profile lookups of different people: 100 x 1 = 100 credits.
- The same profile 100 times within its fresh window: 1 fresh fetch + 99 free cache hits = 1 credit.
- 10 searches: 10 x 5 = 50 credits.
Capping what a key can spend#
Give any key a credit limit in the dashboard. Every charge the key makes counts toward it and refunds are given back; when it is reached that key gets 402 KEY_BUDGET_EXCEEDED and nothing else changes. See Per-key credit limits.
Empty results#
A search that succeeds but finds nothing is a real answer and costs the endpoint price; only failures and not-found records are refunded (see the table above and Refunds).
Try it: Credit cost calculator