Skip to main content

​
Rate Limits & Credits

This page explains how credits and rate limits work across all TopYappers APIs.

​
Credits Pricing

Each API call consumes credits based on the data returned:
APIEndpointCost
Creators API v1GET /api/v1/creators1 credit per creator
Creators API v2GET /api/v2/creators/searchFree
Creators API v2POST /api/v2/creators/get1 credit per creator
Videos APIGET /api/v1/videos1 credit per video
Viral Content APIPOST /api/v1/viral-content1 credit per content
Save credits with v2! Use the Creators API v2 search endpoint for free to find creator IDs, then only pay for the specific creators you need.

​
Rate Limits

All API endpoints are rate limited to 60 requests per minute per API key. When you exceed the rate limit, you’ll receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait. 
{
  "error": "Too many requests",
  "retryAfter": 45
}

​
Response Headers

Every API response includes headers to help you track your usage:

​
x-ty-credits

Your remaining credit balance after the request. 
x-ty-credits: 4523

​
x-ty-rate-limit-remaining

Number of requests remaining in the current rate limit window (resets every minute). 
x-ty-rate-limit-remaining: 55

​
x-ty-rate-limit-total

Your total rate limit allocation per minute. Default is 60 requests/minute. 
x-ty-rate-limit-total: 60
Need higher rate limits? If you require increased rate limits for your use case, please contact support to discuss enterprise options.

​
Example Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
x-ty-credits: 4523
x-ty-rate-limit-remaining: 55
x-ty-rate-limit-total: 60

​
Handling Rate Limits

Here’s how to properly handle rate limits in your code: 
async function fetchWithRateLimitHandling(url, options) {
  const response = await fetch(url, options);
  
  // Check remaining credits
  const credits = response.headers.get('x-ty-credits');
  console.log(`Credits remaining: ${credits}`);
  
  // Check rate limit
  const rateLimit = response.headers.get('x-ty-rate-limit-remaining');
  console.log(`Requests remaining this minute: ${rateLimit}`);
  
  // Handle rate limit exceeded
  if (response.status === 429) {
    const data = await response.json();
    const retryAfter = data.retryAfter || 60;
    console.log(`Rate limited. Retrying in ${retryAfter} seconds...`);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return fetchWithRateLimitHandling(url, options);
  }
  
  return response;
}

​
Best Practices

Monitor Your Usage

Check the x-ty-credits header regularly to avoid running out of credits mid-operation.

Use v2 Search

The v2 search endpoint is free - use it to find exactly the creators you need before fetching full profiles.

Implement Backoff

When you hit rate limits, respect the retryAfter value and implement exponential backoff.

Batch Requests

Use pagination efficiently and batch your requests to stay within rate limits.