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

# Rate limiting

> Understand the shared API and MCP rate limit and learn how to handle it.

# Rate limiting

The Tella public API and MCP server implement rate limiting to ensure fair usage and protect the service for all users.

## Current limits

| Limit               | Value                       |
| ------------------- | --------------------------- |
| Requests per minute | 100                         |
| Scope               | Per user within a workspace |

<Info>
  All API keys and external MCP connections used by the same user in a workspace
  share one 100-request-per-minute limit.
</Info>

## Rate limit headers

Every REST API response includes headers with rate limit information:

| Header                  | Description                                           | Example                   |
| ----------------------- | ----------------------------------------------------- | ------------------------- |
| `RateLimit-Policy`      | Named quota, request limit, and window in seconds     | `"public-api";q=100;w=60` |
| `RateLimit`             | Remaining quota and seconds until the window resets   | `"public-api";r=95;t=42`  |
| `X-RateLimit-Limit`     | Maximum requests per window                           | `100`                     |
| `X-RateLimit-Remaining` | Remaining requests in the current window              | `95`                      |
| `X-RateLimit-Reset`     | Unix timestamp in milliseconds when the window resets | `1704067200000`           |

`RateLimit-Policy` and `RateLimit` use the structured HTTP rate-limit fields. The `X-RateLimit-*` headers remain available for compatibility with existing integrations.

### Example response headers

```http theme={null}
HTTP/1.1 200 OK
RateLimit-Policy: "public-api";q=100;w=60
RateLimit: "public-api";r=95;t=42
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200000
Content-Type: application/json
```

## Handling rate limits

### REST API requests

When a REST API request exceeds the limit, you'll receive a `429` status code:

```json theme={null}
{
  "error": "rate_limited",
  "message": "Too many requests",
  "docsUrl": "https://docs.tella.com/"
}
```

The response also includes `Retry-After` with the number of seconds to wait before retrying.

### MCP tool calls

When an MCP tool call exceeds the limit, the server returns a tool error instead of an HTTP `429` response. The result includes the number of seconds to wait and marks the error as retryable:

```json theme={null}
{
  "isError": true,
  "structuredContent": {
    "errorCode": "rate_limited",
    "retryable": true
  }
}
```

Wait for the duration in the first text content block before retrying the tool call.

### Best practices

<AccordionGroup>
  <Accordion title="Check remaining requests">
    Monitor the `X-RateLimit-Remaining` header and slow down before hitting the limit.

    ```javascript theme={null}
    const response = await fetch('https://api.tella.com/v1/videos', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });

    const remaining = response.headers.get('X-RateLimit-Remaining');
    if (parseInt(remaining) < 10) {
      console.log('Approaching rate limit, slowing down...');
    }
    ```
  </Accordion>

  <Accordion title="Respect retry timing">
    When you receive a REST API `429`, respect `Retry-After`. For a retryable MCP error, wait for the duration in its text content before retrying:

    ```javascript theme={null}
    async function fetchWithRetry(url, options, maxRetries = 3) {
      for (let i = 0; i < maxRetries; i++) {
        const response = await fetch(url, options);

        if (response.status === 429) {
          const retryAfter = Number(response.headers.get('Retry-After') ?? 1);
          const waitTime = retryAfter * 1000;
          console.log(`Rate limited. Waiting ${waitTime}ms...`);
          await new Promise(r => setTimeout(r, waitTime));
          continue;
        }

        return response;
      }
      throw new Error('Max retries exceeded');
    }
    ```
  </Accordion>

  <Accordion title="Use the reset timestamp">
    The `X-RateLimit-Reset` header tells you exactly when your limit resets, in Unix epoch milliseconds:

    ```javascript theme={null}
    const resetTime = response.headers.get('X-RateLimit-Reset');
    const waitMs = parseInt(resetTime) - Date.now();

    if (waitMs > 0) {
      console.log(`Waiting ${waitMs}ms until rate limit resets`);
      await new Promise(r => setTimeout(r, waitMs));
    }
    ```
  </Accordion>

  <Accordion title="Batch requests efficiently">
    Instead of making many small requests, use pagination efficiently:

    ```javascript theme={null}
    // Instead of fetching videos one by one
    // Fetch them in batches using the list endpoint
    let cursor = null;
    const allVideos = [];

    do {
      const url = cursor
        ? `https://api.tella.com/v1/videos?cursor=${cursor}`
        : 'https://api.tella.com/v1/videos';

      const response = await fetch(url, { headers });
      const data = await response.json();

      allVideos.push(...data.data);
      cursor = data.pagination.next_cursor;
    } while (cursor);
    ```
  </Accordion>
</AccordionGroup>

## Rate limit scope

Rate limits are calculated per user within an organization:

* All API keys and external MCP connections used by the same user share the same 100 requests per minute limit
* Different users in the same organization have independent limits
* REST API requests and MCP tool calls draw from the same limit

## Need higher limits?

If your use case requires higher rate limits, please [contact us](mailto:support@tella.com) to discuss your needs.


## Related topics

- [Quickstart](/docs/quickstart.md)
- [Introduction](/docs/introduction.md)
- [Model Context Protocol (MCP)](/docs/mcp-server.md)
- [Export raw camera and screen recordings](/docs/help/export-videos/export-raw-recordings.md)
- [Delete a video](/docs/api-reference/videos/delete-a-video.md)