Billing: prepaid balance, holds and what is free

You pay from a prepaid balance in US dollars. Each successful call takes its listed price from it, and a failed call takes nothing. There is no subscription and nothing renews: you top up when the balance runs low, 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 Douyin video comments costs $0.002 whether it holds three comments or 20.
item: the price times the items returned, never less than the endpoint's minimum and never more than its maxCharge for 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 call fails, the whole hold goes back.

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

Every error. Its body says charged: false: timeouts, platform failures, bad parameters and rate limits alike, and not_found on most endpoints. The exceptions are not_found on the few endpoints that charge for it (next section; the body then says charged: true with amount) and settlement_unknown, below. The errors page lists them all.
Resending a call with the same Idempotency-Key within 24 hours.
A batch call in which nothing was found.
Reading a stored result again at GET https://api.okdata.online/v1/calls/{request_id}/result, for 24 hours.
The catalog, status, account, calls and usage routes, and the MCP tools find and describe.

What an empty answer and a "not found" cost is set per endpoint. On most endpoints, not found is free and an empty answer costs the normal price (one item, or the minimum, on a per-item endpoint). A few Douyin endpoints, such as Douyin index: brand trends, work the other way round. Each platform's table on the pricing page shows both, and /prices.json gives them for every endpoint as charge_when_empty and charge_when_not_found.

meta.billing

Every success carries its bill:

"billing": { "amount": "0.02", "currency": "USD", "balance_after": "9.98" }

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 an Idempotent-Replayed: true header.
The same key with a different request is 409 idempotency_conflict. While the first call is still running, it is 409 call_in_progress: retry with the same key.
A not_found or invalid_params answer is kept for the key and given again for the 24 hours. Any other failure frees the key, so a resend runs anew.
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 at GET https://api.okdata.online/v1/calls/{request_id}.

import os
import uuid
import requests

URL = "https://api.okdata.online/v1/douyin/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": "7301234567890123456"}, 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 $100 you get 10% extra credit and from $500, 20%. Bonus credit spends like the rest.
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.

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, and not for throwaway email domains. 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/account returns the balance and the key's spending limits; it is free.
GET https://api.okdata.online/v1/calls/{request_id} says whether a call was settled or released and what it was charged.
GET https://api.okdata.online/v1/usage?group_by=day,capability totals calls and charges for the last 30 days (up to 92); add format=csv for a spreadsheet.

curl -s "https://api.okdata.online/v1/account" -H "Authorization: Bearer $OKDATA_API_KEY"