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.

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 and monthly spending determine your rate limits.

Plans overview

TwelveLabs offers three plans:

• Free plan: Basic limits at no cost
• Developer plan: Three tiers that increase with monthly spending
• 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, POST /knowledge-stores/{knowledge_store_id}/search
• Analyze: POST /analyze

Free plan

New accounts start with the Free plan at no cost.

The embedding limits depend on the model you use:

Developer plan

The Developer plan has three tiers. You start at Tier 1 when you add a payment method. Your tier increases automatically based on your monthly spending.

Tier qualifications

See the Pricing page to calculate your spending.

Rate limits by tier

Enterprise plan

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

Tier upgrades and downgrades

Upgrades: The platform upgrades your account when you reach the spending requirement for a higher tier. The upgrade takes effect immediately. You receive an email notification when your tier changes.

Downgrades within the Developer plan: When your monthly spending falls below your current tier’s threshold, a one-month grace period applies before a downgrade.

Example:

• First month: You spend less than $200 (below the Tier 2 threshold)
• Beginning of the second month: The platform sends you an email notification
• Second month: You spend less than $200 again
• Beginning of the third month: The platform downgrades you to Tier 1

Plan downgrades: When you downgrade from the Developer plan to the Free plan, the tier change takes effect immediately, with no grace period.

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 on the Developer plan at Tier 1, combining 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:

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

When you exceed an input token limit:

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

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

Upgrade your plan or tier to increase rate limits:

1. Add a payment method: Access Tier 1
2. Increase spending: Reach Tier 2 or Tier 3
3. Contact sales: Request custom Enterprise limits