> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topyappers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits & Credits

> Understanding API pricing, credits, and rate limits

# 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:

| API                    | Endpoint                      | Cost                              |
| ---------------------- | ----------------------------- | --------------------------------- |
| **Creators API v1**    | `GET /api/v1/creators`        | 1 credit per creator              |
| **Creators API v2**    | `GET /api/v2/creators/search` | **Free**                          |
| **Creators API v2**    | `POST /api/v2/creators/get`   | 1 credit per creator              |
| **CRM API v2**         | `/api/v2/crm/*`               | **Free with active subscription** |
| **Videos API**         | `GET /api/v1/videos`          | 1 credit per video                |
| **Viral Content API**  | `POST /api/v1/viral-content`  | 1 credit per content              |
| **Songs API**          | `GET /api/v1/songs`           | 10 credits per request            |
| **Agent Outreach API** | `GET /api/v1/agent/*`         | **Free**                          |

<Tip>
  **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.
</Tip>

## 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.

```json theme={null}
{
  "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
```

<Note>
  **Need higher rate limits?** If you require increased rate limits for your use case, please [contact support](mailto:support@topyappers.com) to discuss enterprise options.
</Note>

## Example Response Headers

```http theme={null}
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:

<CodeGroup>
  ```javascript JavaScript theme={null}
  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;
  }
  ```

  ```python Python theme={null}
  import requests
  import time

  def fetch_with_rate_limit_handling(url, headers):
      response = requests.get(url, headers=headers)
      
      # Check remaining credits
      credits = response.headers.get('x-ty-credits')
      print(f"Credits remaining: {credits}")
      
      # Check rate limit
      rate_limit = response.headers.get('x-ty-rate-limit-remaining')
      print(f"Requests remaining this minute: {rate_limit}")
      
      # Handle rate limit exceeded
      if response.status_code == 429:
          data = response.json()
          retry_after = data.get('retryAfter', 60)
          print(f"Rate limited. Retrying in {retry_after} seconds...")
          time.sleep(retry_after)
          return fetch_with_rate_limit_handling(url, headers)
      
      return response
  ```
</CodeGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Monitor Your Usage" icon="chart-line">
    Check the `x-ty-credits` header regularly to avoid running out of credits mid-operation.
  </Card>

  <Card title="Use v2 Search" icon="magnifying-glass">
    The v2 search endpoint is free - use it to find exactly the creators you need before fetching full profiles.
  </Card>

  <Card title="Implement Backoff" icon="clock">
    When you hit rate limits, respect the `retryAfter` value and implement exponential backoff.
  </Card>

  <Card title="Batch Requests" icon="layer-group">
    Use pagination efficiently and batch your requests to stay within rate limits.
  </Card>
</CardGroup>