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

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

Video analytics

Video analytics (GET /v1/videos/{id}/analytics and the get_video_analytics MCP tool) also has a separate limit of 30 requests per minute for each workspace, shared by every user and key in that workspace. Each request still counts toward the 100-request limit. The rate limit headers show only the 100-request limit, but the 429 response and the MCP error work the same way for both limits. To sync analytics for many videos, spread the requests out or use workspace analytics, which lists each video’s views, sessions and average percent viewed, up to 100 videos per page.

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

{
  "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:

{
  "isError": true,
  "_meta": {
    "com.tella/error": {
      "errorCode": "rate_limited",
      "retryable": true
    }
  }
}

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

Best practices

Check remaining requests

Monitor the X-RateLimit-Remaining header and slow down before hitting the limit.

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...');
}

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:

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');
}

Use the reset timestamp

The X-RateLimit-Reset header tells you exactly when your limit resets, in Unix epoch milliseconds:

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));
}

Batch requests efficiently

Instead of making many small requests, use pagination efficiently:

// 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);

Rate limit scope

The 100-request-per-minute limit is per user within a workspace. All API keys and external MCP connections used by the same user share it; other users in the workspace have independent 100-request limits. REST API requests and MCP tool calls both count toward this limit. The 30-request-per-minute video analytics limit is shared across the workspace. Requests to GET /v1/videos/{id}/analytics and calls to get_video_analytics from any user or key in that workspace count toward the same 30-request limit, as well as the caller’s 100-request limit.

Need higher limits?

If your use case requires higher rate limits, please contact us to discuss your needs.

Getting Started

Guides

MCP Tools

API Reference

Webhooks

Rate limiting

Rate limiting

Current limits

Video analytics

Rate limit headers

Example response headers

Handling rate limits

REST API requests

MCP tool calls

Best practices

Rate limit scope

Need higher limits?

​Rate limiting

​Current limits

​Video analytics

​Rate limit headers

​Example response headers

​Handling rate limits

​REST API requests

​MCP tool calls

​Best practices

​Rate limit scope

​Need higher limits?

Rate limiting

Current limits

Video analytics

Rate limit headers

Example response headers

Handling rate limits

REST API requests

MCP tool calls

Best practices

Rate limit scope

Need higher limits?