Plans and limits

Each plan's limits, and how the API meters requests and stream units against them.

Every key belongs to an account on a plan, and the plan sets how fast and how much the account may ask.

Plans

The table is read live from GET /v1/plans, which takes no key.

The per-minute budget counts requests: each costs one, whatever its units. The monthly allowance counts units.

Stream units, per key and clock hour: ⌈connection seconds ÷ 60⌉ + ⌈filter-score seconds ÷ 60,000⌉ + ⌈events delivered ÷ 1,000⌉.

Upgrading

Pro is bought on the web, from the API tab of your Traktor profile, and only while that tab offers Upgrade to Pro: it opens Stripe Checkout, and the account moves to Pro once Stripe confirms the payment. An account Stripe bills changes its card, reads its invoices or cancels from Manage billing on the same tab, which opens Stripe's billing portal; a cancelled plan stays Pro until the period paid for ends. The Traktor app sells nothing.

Requests and units

Each route's cost in units is on its endpoint block. The per-minute budget and the monthly allowance belong to the account, so every key it holds draws on the same two. A 304 draws no units and still counts as a request. The alert, notification and Telegram routes draw no units; their per-account limit is on their endpoint blocks and under Every limit.

Limit headers

A metered route sets these headers on every answer to a request it admits, internal_error aside, and on a 429 from its budgets:

A script in a browser can read every one but X-Traktor-Plan and RateLimit-Policy.

A refusal raised before admission carries none of these headers and draws on neither budget. One raised after admission counts against the per-minute budget, and its units come back: X-Traktor-Cost: 0. Where each refusal falls:

• GET /v1/market and its views refuse every fault in the query before admission: a repeated key, the grammar's and paging's refusals, plan_forbids and route_not_found. What fails once the read starts comes after: filter_too_broad, data_unavailable, market_busy and market_fold_pending.

• GET /v1/signals refuses a fault in its query before admission, and a cursor's refusals after: invalid_cursor, cursor_query_mismatch and cursor_expired.

• An internal_error after admission gives its units back too, and its answer carries none of these headers.

When a budget runs out

• 429 rate_limited: the per-minute budget is spent. Wait for Retry-After, then retry.

• 429 quota_exhausted: the period's units are spent, or fewer remain than the request costs. details.resetsAt says when they return, and RateLimit-Reset counts down to it; waiting a minute will not help. The refusal still counts against the per-minute budget.

• 503 rate_limit_unavailable: the limiter could not be asked. Retry after Retry-After.

Neither 429 draws units.

Stream units

The trade stream, and the market stream under a key, draw on the account's monthly allowance of stream units, counted per key and clock hour by the formula under the plans table. A keyed market socket's seconds open count as connection seconds, and each view it is sent as an event delivered. The count it is checked against is refreshed every 15 minutes, so it trails your use by up to that long. The trade stream checks it when you authenticate, when you resume with from, and every minute, the market stream before the upgrade and every minute, and each closes with 4006 quota_exhausted once the count passes the allowance.

Every limit

Each route's limits, as its endpoint block states them; routes with the same limits share a row. A route that takes an API key also draws on its account's per-minute budget and units, above.

Every per-IP limit counts an IPv6 caller by its /64.

The per-IP limits of GET /v1/public/market and GET /v1/public/search, the market stream's keyless connections and the trade stream's sockets not yet authenticated are counted by each API server on its own, and the API runs on more than one, so a client past one of those limits can still be answered by a server whose count is below it. Each server refuses an IP once its own count passes the limit, so keep to the number in the table. Every other per-IP limit, invalid keys included, and every per-account one, is counted across all of them.

Those two reads count an IP's requests in a minute that starts at its first one, not a rolling minute, so up to twice the limit can be answered across the turn of a minute. Each server counts at most 10,000 IPs on each of them; while it holds that many, a request from an IP it is not counting yet takes the place of the IP whose minute started first, which starts a new minute at its next request.

Going past "Invalid keys" never answers 429: the refusal stays 401 invalid_key, even for a valid key the server has to look up again, until the budget refills (When a key is refused).