Endpoint previews
Preview access lets you test eligible REST endpoints before upgrading. Each endpoint page lists the plans with preview access and the plans with production access. Production access uses your normal plan limits without the five-request preview allowance.
Make a preview request
Call the endpoint's usual URL with your existing API key in the x-access-token header. No preview parameter or separate API key is needed. You must have an active API subscription; an anonymous request cannot use preview access.
For example, a Free, Basic or Startup account can preview coin supply history:
curl https://api.coinranking.com/v2/coin/Qwsogvtv82FCd/supply-history \
-H 'x-access-token: your-api-key'Daily allowance
You can make five successful requests per restricted endpoint per account per UTC day. The allowance resets at 00:00 UTC. A successful response has a 2xx HTTP status. Failed requests do not consume this preview allowance, although normal rate limits still apply.
The allowance is shared across every API key belonging to your account. Changing resource IDs, query parameters or pagination does not create another allowance. For example, BTC and ETH supply-history requests share the same five requests. Supply history and global market-cap history have separate allowances because they are different endpoints.
Each successful preview also counts toward your normal API usage. Preview access does not provide an extra monthly request allowance.
Plan limits still apply
| Limit | Free | Basic | Startup and Growth |
|---|---|---|---|
| Maximum results per response | 100 | 5,000 | 5,000 |
| Historical window, where supported | Past year | Past five years | All available history |
These limits apply to both preview and production requests. Preview access does not unlock a higher plan's result limit, historical window or rate limits. An endpoint can return fewer results or a shorter history when less data is available.
Standard DEX endpoints offer previews to Free, Basic and Startup accounts. Production access requires Growth or higher. Bulk coins download and raw DEX data do not offer previews.
Response headers
Preview responses include headers for this account's allowance on the requested endpoint:
| Header | Meaning |
|---|---|
x-preview-limit | Maximum successful previews per UTC day, normally 5. |
x-preview-used | Successful previews already counted today. |
x-preview-remaining | Available requests after successful previews and requests currently in progress are reserved. |
x-preview-reset | Unix timestamp in seconds for the next reset at 00:00 UTC. |
Requests currently in progress temporarily reserve a slot, so x-preview-remaining can be lower than x-preview-limit minus x-preview-used.
When the allowance is unavailable
| Error code | HTTP status | What to do |
|---|---|---|
PREVIEW_LIMIT_REACHED | 429 | Wait until the next UTC day or upgrade to a plan with production access. |
PREVIEW_CAPACITY_BUSY | 503 | Other requests have reserved the available preview slots. Retry after the Retry-After delay. |
PREVIEW_UNAVAILABLE | 503 | Preview access is temporarily unavailable. Retry with backoff. |
For PREVIEW_LIMIT_REACHED, Retry-After gives the number of seconds until the next daily reset. See the error reference for the gateway error response format.