API Keys, Credits and Usage Limits
Both key types authenticate through x-api-key. Read key_type in GET /v1/usage/info to determine the applicable model.
| Credits API key | Subscription API key | |
|---|---|---|
key_type | credits | subscription |
| Payment | Operations spend credits from the applicable personal or team wallet | An API package provides configured allowances |
| Feature access | Free, Pro, Advanced or Team API access | Features are configured for the individual key |
| Request and channel limits | Plan ceilings apply in addition to credit charges | Allowances are configured for the key |
| Getting the current key | /api_key in the API bot | /api_key returns it if it already exists |
Three independent checks
A call must have feature access, fit within its usage limits, and, for a paid credits operation, have sufficient available credits.
Adding credits does not increase request/channel ceilings or unlock a feature outside your API plan. An available balance also does not override an inactive key or an ended funding subscription. A Free plan can provide active access within its own restrictions.
The key is not a separate wallet. A team-funded user can spend the shared team wallet while retaining that user's own API usage counters.
Credit units and response headers
1 credit = 1,000 milli-credits (mc). Monetary fields and credit headers use integer milli-credits.
| Header | Meaning |
|---|---|
x-credits-cost | The settled cost of this call, in mc |
x-credits-remaining | The available balance reported after settlement, in mc |
These headers apply to settled credits calls. Free endpoints and failed requests may not include them. Treat missing headers as missing information, not a zero balance.
For example, x-credits-cost: 801 means 0.801 credits, not 801 credits.
What makes a call cost more?
- Ordinary billable calls have a base request fee.
- Channel-specific calls can additionally charge for each channel first accessed with this key in the current period. The same channel is not charged again as a new channel until the next period.
- A batch channel-info call can introduce several new channels.
- Catalog search has its own inclusive request price.
- Snapshot and diff creation each cost 0.400 credits, including an empty diff. Reads cost 0.001 per request/page; deletion with a Credits key is free. These are the agreed release prices; activation depends on deployment and runtime price configuration.
- Post search has its own inclusive request price and can additionally charge for a search term first used in the current period.
- Dictionaries and usage information do not consume request quota or credits.
A repeated call can still incur its request charge even when the channel or search term is already known. The tariff page separates access and quotas from prices.
Read usage correctly
GET /v1/usage/info returns the period boundaries and counters such as:
{
"key_type": "credits",
"status": "Active",
"requests": {"spent": 154, "limit": 1000},
"channels": {"spent": 2, "limit": 10},
"search_messages_requests": {"spent": 0, "limit": 100},
"search_terms": {"spent": 0, "limit": 10},
"billing_start_date": "2026-09-01T00:00:00Z",
"billing_end_date": "2026-10-01T00:00:00Z"
}
The values above are illustrative. Use the returned period dates instead of assuming the first day of a calendar month.
For Credits API keys, requests and channels are enforced ceilings. The two search rows are retained for response compatibility: their limit values are informational, not additional search ceilings. search_messages_requests.spent = 0 is not evidence that no searches were made. Search calls still contribute to overall billable request usage.
For Subscription API keys, the request, channel, search-request and unique-search-term allowances are enforced according to that key's settings. The response has the same fields with key_type: "subscription".
Usage information does not expose a wallet balance or a public REST wallet-management API. See errors and retries for insufficient credits and quota exhaustion.