Billing: prepaid balance, holds and what is free
How okdata charges: a prepaid USD balance, per call or per item, a hold before each call settled after it, what is free, Idempotency-Key, top-ups and the trial credit.
You pay from a prepaid balance in US dollars. A call that reaches a data source is charged, even when the answer comes back empty, not found or failed; a call stopped before it reaches a source (bad parameters, a low balance) is free. There is no subscription, and by default nothing charges your card: you top up when the balance runs low, or turn on auto top-up to refill from a bank card by rules you set, and every answer says what the call cost and what is left.
Per call or per item
Every endpoint has a unit, shown on its page and on the pricing page:
call: one price per request, however many results come back. A page of TikTok video comments costs $0.002 whether it holds three comments or 50.item: the price times the items returned, never less than the endpoint'sminimumand never more than itsmaxChargefor one call. X account search costs $0.0004 per account: a full page of 20 accounts costs $0.008, and an empty page is billed as one item.
Scripts can read the same numbers from /prices.json as unit, price, minimum and max_charge.
Hold, then settle
Every paid call runs the same steps:
- Before we ask the platform, we hold the most the call can cost: the price on a per-call endpoint, a full page on a per-item list, and one item for each id asked on a per-item lookup, up to its most per call.
- If the balance cannot cover the hold, the call stops with
402 insufficient_balance. Nothing is taken. - When the data comes back, we settle the real charge and give back the rest of the hold. When the source fails or times out, we settle one unit (the price, or one item on a per-item endpoint) and give back the rest. An error on our side gives back the whole hold.
A running call's hold is out of your balance until it settles, so calls running side by side each need their own room. One exception keeps small balances useful: the first page of a per-item list (no cursor) that the balance cannot cover in full is cut to the items it can pay for. warnings says so, and that page has no next cursor. Spending limits you set on a key in the console (per UTC day, month or in total) count holds too, and a call that would pass one is refused with 402 key_budget_exceeded, never charged.
What costs nothing
- A call stopped before it reaches a data source: bad parameters (
invalid_params), an insufficient balance, a missing or revoked key, a key's spending limit, rate limits (rate_limited),max_pricerefusals and paused endpoints (capability_paused). Its body sayscharged: false. - An error on our side (
internal_error). - Getting a stored result back by resending with the same
Idempotency-Keywithin 24 hours. - Reading a stored result again at
GET https://api.okdata.online/v1/calls/{request_id}/result, for 24 hours. - An empty or
not_foundanswer given from the result cache (meta.cached: true): the data source was not asked again. A cachednot_foundsayscharged: false. - The catalog, status, account, calls and usage routes, and the MCP tools
find,describeandaccount.
A call that reached a data source is charged once at the endpoint's normal price even when the answer is empty, not found (not_found), or the source failed or timed out (upstream_failed, upstream_busy, timeout). On a per-item endpoint that is one item. Retries on our side do not multiply it: it is one charge per call. The error body then says charged: true with amount. Budget for empty and failed answers like any other call. An answer with data from the result cache costs the endpoint's normal price, the same as a fresh read. settlement_unknown is below, and the errors page lists every code; prices are on the pricing page.
meta.billing
Every success carries its bill:
"billing": { "amount": "0.002", "currency": "USD", "balance_after": "9.998" }
amount is this call's charge and balance_after is the balance once it settled, both decimal strings in US dollars. Add them up as decimals, never as floats.
Idempotency-Key
Send an Idempotency-Key header, 1 to 255 visible ASCII characters (a UUID works), and keep it with the request until you have an answer. The keys belong to the account, so all its API keys share them.
- The same key with the same request within 24 hours returns the stored result:
meta.replayed: true,amount: "0", and anIdempotent-Replayed: trueheader. - The same key with a different request is
409 idempotency_conflict. While the first call is still running, it is409 call_in_progress: retry with the same key. - A
not_foundorinvalid_paramsanswer is kept for the key and given again for the 24 hours. Any other failure frees the key, so a resend is a new call, charged again if it reaches a data source. settlement_unknown(charged: null) means the data came back but the charge could not be confirmed. Resend with the same key to get the result without paying twice, or look the call up atGET https://api.okdata.online/v1/calls/{request_id}.
import os
import uuid
import requests
URL = "https://api.okdata.online/v1/tiktok/videos/comments/list"
key = str(uuid.uuid4()) # reuse it for every resend of this request
headers = {"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}", "Idempotency-Key": key}
body = requests.get(URL, headers=headers, params={"id": "7305085486984858894"}, timeout=60).json()
if body["code"] == "ok":
bill = body["meta"]["billing"]
print("paid", bill["amount"], "left", bill["balance_after"], "replayed", body["meta"]["replayed"])
else:
print(body["code"], "charged:", body["charged"], body["message"])
The price book
Prices belong to a price book whose version changes whenever any endpoint's unit, price, minimum, most per call, or empty and not-found charge changes. /prices.json gives it as price_book, with effective_at once its start is recorded, and GET https://api.okdata.online/v1/catalog as priceBook. Store the version next to your cost estimates; if it changed, read the prices again.
Top-ups
- Whole dollars from $10 to $10,000 a top-up. From $50 you get 3% extra credit, from $100 6%, from $500 10% and from $1,000 12%; $10 and $25 top-ups get none. Bonus credit spends like the rest.
- Once you have paid $50 in all, every later top-up gets another 2%; from $200 paid it is 4%, and from $1,000 paid 6%. This stacks with the bonus above, so the most a top-up can get is 18% extra. Only money you actually paid counts: completed top-ups, plus any payment dispute decided in our favour. Fully refunded top-ups, disputes we lost and free credit (the trial, referrals, promotions) do not count. The level depends on what you had paid before this top-up, not including it. It applies to WeChat Pay, Alipay, card and auto top-up alike. The console's Billing page shows how much you have paid and how much more takes you to the next level, and the breakdown before you pay lists this bonus on its own line.
- Pay by card through Stripe in US dollars (Visa, Mastercard, Amex, Apple Pay), or by Alipay or WeChat Pay through XorPay in yuan, at the rate shown before you pay. Alipay takes up to ¥1,000 a payment, WeChat Pay up to ¥20,000.
- Top-ups are final, and the balance never expires.
Auto top-up
Auto top-up is off unless you turn it on. When it is on, your bank card is charged whenever the balance drops below a line you set, so an agent that runs for hours does not stop on insufficient_balance. It works with bank cards only, not Alipay or WeChat Pay.
- Turning it on. Tick the auto top-up box when you pay by card, or turn it on in the console's Billing page. Turning it on there only saves the card and charges nothing, unless your balance is already below your line, in which case one top-up runs straight away.
- Three settings. The line: top up when the balance falls below it, a whole number from $1 to $100, $5 by default, and lower than the amount. The amount: $25, $50, $100 or $500 each time, $50 by default; the usual bonuses apply: 3% on $50, 6% on $100 and 10% on $500, plus the paid-in-all bonus above. The monthly cap: from one top-up's amount up to $5,000, $200 by default, counted per calendar month in UTC.
- When it charges. After a call leaves the balance below the line, or when a call is refused for insufficient balance. At most three top-ups a day (UTC days).
- The monthly cap. Once the month's top-ups reach the cap (UTC calendar month), nothing more is charged that month. You get one email, auto top-up stays on, and it picks up again next month.
- Emails. A confirmation when you turn it on, a receipt for every charge, and an email when a charge fails or the cap is reached.
- When it turns itself off. If the card is declined or the bank asks for cardholder verification, auto top-up turns off and you get an email; add the card again to turn it back on. A card dispute on the account also turns it off.
- Turning it off. Any time, in the console. The card is then removed and not kept.
- On your card statement the merchant name includes OKDATA.
It is still not a subscription: there is no monthly fee, and it only tops up by the rules you set.
Trial credit
A new account gets $0.10 of free credit when it first signs in to the console: once per account and per mailbox. Until the first top-up the account is on the trial tier, with lower limits; see rate limits.
Checking what you spent
- The console call log lists every call with its request ID, status and cost, filtered by endpoint, status and date. Billing shows your top-ups and spend by platform.
GET https://api.okdata.online/v1/accountreturns the balance and the key's spending limits; it is free.GET https://api.okdata.online/v1/calls/{request_id}says whether a call wassettledorreleasedand what it wascharged.GET https://api.okdata.online/v1/usage?group_by=day,capabilitytotals calls and charges for the last 30 days (up to 92); addformat=csvfor a spreadsheet.
curl -s "https://api.okdata.online/v1/account" -H "Authorization: Bearer $OKDATA_API_KEY"
Updated