Rate limits control how many requests you can make within a specific time window. These limits ensure fair usage and maintain optimal performance for all users.

TwelveLabs is moving plans to the new billing in phases. Legacy billing applies to your plan until it moves. This page describes the rate limits of the new billing. For the dates, see Migrate to the new billing. For legacy billing, see Legacy billing rate limits.

Understand rate limits

The platform uses multiple dimensions to measure your usage. Each dimension tracks different aspects of your requests. Understanding how rate limits work helps you optimize your usage and avoid errors.

Rate limit dimensions

The platform measures your usage across these dimensions:

• DPD: Duration per day (in minutes)
• DPH: Duration per hour (in minutes)
• RPD: Requests per day
• RPM: Requests per minute
• TPD: Tokens per day
• TPM: Tokens per minute

Rate limits vary by endpoint based on computational requirements:

• Duration-based limits (DPH, DPD) apply to endpoints that process video or audio content. They do not apply to embedding with Marengo 3.5.
• Token limits (TPM, TPD) count the output tokens on endpoints that generate text. For embedding, they count the input tokens and apply only with Marengo 3.5.
• Request limits (RPM, RPD) apply to all endpoints.

Exceeding a limit

The platform checks your usage against each applicable dimension. You receive an error when you exceed any limit, even if other dimensions have remaining capacity.

For example, you might have remaining request capacity (RPM) but exceed your duration limit (DPH) when processing a long video. The platform returns an error based on the duration limit.

Your rate limits

Your plan determines your rate limits.

Plans overview

The new billing has the following plans:

• Free plan: Basic limits at no cost
• Plus and Pro plans: The same limits for both plans, higher than the Free plan
• Enterprise plan: Custom limits based on your requirements

Rate limit categories

Rate limits are grouped into categories. Endpoints in the same category share a rate limit. All requests to these endpoints count toward the shared limit. An endpoint can have different rate limits based on the type of content you process.

• Index: POST /tasks, POST /indexes/{index-id}/indexed-assets
• Upload: POST /assets
• Embed - Video: POST /embed, POST /embed/tasks, POST /embed-v2, POST /embed-v2/tasks
• Embed - Audio: POST /embed, POST /embed-v2, POST /embed-v2/tasks
• Embed - Image: POST /embed, POST /embed-v2
• Embed - Document: POST /embed-v2/tasks
• Embed - Text: POST /embed, POST /embed-v2
• Embed - Text_Image: POST /embed-v2
• Search: POST /search
• Analyze: POST /analyze
• Jockey Search: POST /knowledge-stores/{knowledge_store_id}/search
• Jockey Response: POST /responses

Free plan

The embedding limits depend on the model you use:

Plus and Pro plans

The embedding limits depend on the model you use:

Enterprise plan

The Enterprise plan provides custom rate limits. Contact us to discuss your requirements.

Input token limits for embedding

When you embed content with Marengo 3.5, the platform counts input tokens. For Marengo 3.0, duration limits apply instead.

Each type of content has its own limit: video, audio, image, document, and text. The platform never adds the counts of different types into a shared total. One request can count against several limits at once. A request that combines a video and an image counts against the video limit and the image limit. The response contains a usage.input_tokens object with the token count for each type of content. Each key identifies the limit those tokens counted against.

The platform counts the tokens of a request only after the model processes it. You can exceed a limit before you see an error:

• You still receive a success response for the request that exceeds a limit. An asynchronous task that exceeds a limit still completes.
• You receive the HTTP 429 - Too Many Requests error on your next request. The platform checks your limits before it processes anything, and it does not count any tokens for that request.
• A success response is not proof that you were within your limits. To check your remaining capacity, read the Remaining header for the type of content you sent.

The platform checks only the content you include in your request. A file can contain more than one type of content, such as a video with an audio track. The platform counts the tokens of the extra type only after it returns the response. If you have exceeded only that limit, one more request can succeed before you see the error.

Work with rate limits

Use response headers to track your usage, implement best practices to handle errors, and upgrade your plan when you need higher limits.

Monitor your usage

Check your usage using HTTP response headers.

Response headers

Each response includes headers for the active dimensions:

For the input token headers, <type> is Video, Audio, Image, Document, or Text.

Build a header name from X-Ratelimit-Dimensions

The X-Ratelimit-Dimensions header lists the label of every limit the request was measured against. The labels are comma-separated and sorted alphabetically. Replace <label> with an entry from the list to build the header names for that limit: X-Ratelimit-<label>-Limit, X-Ratelimit-<label>-Remaining, and X-Ratelimit-<label>-Reset.

The list keeps the mixed-case spelling of each label, such as InputToken-Video. The platform sends the headers in the canonical form, such as X-Ratelimit-Inputtoken-Video-Limit. HTTP header names are case-insensitive, so the two spellings match. If your code copies raw header names into a case-sensitive map, lowercase them first.

Legacy headers

These headers contain aggregate rate limit information. The platform maintains them for backward compatibility. Use the X-Ratelimit-<label>-* headers instead. The /embed-v2 and /embed-v2/tasks endpoints do not send these headers. On those endpoints, only the X-Ratelimit-Request-* headers contain the request limit.

Example response headers

A request measured on requests and duration:

X-Ratelimit-Dimensions: Duration,Request
X-Ratelimit-Request-Limit: 600
X-Ratelimit-Request-Remaining: 542
X-Ratelimit-Request-Reset: 1735689600
X-Ratelimit-Duration-Limit: 3000
X-Ratelimit-Duration-Remaining: 2847
X-Ratelimit-Duration-Reset: 1735689600

A Marengo 3.5 request that combines a video, an image, and text:

X-Ratelimit-Dimensions: InputToken-Image,InputToken-Text,InputToken-Video,Request
X-Ratelimit-Request-Limit: 25
X-Ratelimit-Request-Remaining: 24
X-Ratelimit-Request-Reset: 1735689600
X-Ratelimit-Inputtoken-Video-Limit: 50000000
X-Ratelimit-Inputtoken-Video-Remaining: 49994000
X-Ratelimit-Inputtoken-Video-Reset: 1735689600
X-Ratelimit-Inputtoken-Image-Limit: 1000000
X-Ratelimit-Inputtoken-Image-Remaining: 999000
X-Ratelimit-Inputtoken-Image-Reset: 1735689600
X-Ratelimit-Inputtoken-Text-Limit: 1000000
X-Ratelimit-Inputtoken-Text-Remaining: 999975
X-Ratelimit-Inputtoken-Text-Reset: 1735689600

Handle rate limit errors

The platform returns an HTTP 429 - Too Many Requests error when you exceed a rate limit. The message field contains the limit you exceeded and the time it resets. The response includes a Retry-After header with the number of seconds to wait.

For an input token limit, you receive the error on the request after the one that exceeded it. See Input token limits for embedding.

Error response format

When you exceed a duration limit:

{
  "code": "too_many_requests",
  "message": "You have exceeded the rate limit (3000sec/1hour). Please try again later after 2025-12-03T14:30:00Z."
}

When you exceed an input token limit:

{
  "code": "too_many_requests",
  "message": "You have exceeded the rate limit (1000000token/1minute). Please try again later after 2025-12-03T14:30:00Z."
}

Best practices

Follow these practices to handle rate limit errors:

• Check response headers: Monitor your remaining capacity before making requests
• Respect the Retry-After header: Wait the number of seconds it specifies before retrying
• Implement exponential backoff: Increase the time between retries
• Distribute requests: Spread the calls evenly instead of sending bursts
• Cache responses: Reuse responses when possible to reduce requests

Increase your limits

To increase your rate limits, move from the Free plan to the Plus or Pro plan. For the available plans, see the Pricing page.