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 (in thousands)
• TPM: Tokens per minute (in thousands)

Rate limits vary by endpoint based on computational requirements:

• Duration-based limits (DPH, DPD) apply only to endpoints that process video or audio content
• Token limits (TPM, TPD) apply only to endpoints that generate text output
• Request limits (RPM, RPD) apply to all endpoints

How the platform measures limits

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 vary by modality. 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
• Embedding - Text: POST /embed, POST /embed-v2
• Embedding - Text_Image: POST /embed-v2
• Search: POST /search
• Analyze: POST /analyze
• Summarize: POST /summarize

Free plan

New accounts start with the Free plan at no cost.

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.

How tier changes work

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)
• End of first 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.

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:

Legacy headers

These headers provide aggregate rate limit information. The platform maintains them for backward compatibility but they will be removed in a future release:

Example response headers

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

Handle rate limit errors

The platform returns an HTTP 429 - Too Many Requests error when you exceed a rate limit. The error shows which limit you exceeded and when it resets.

Error response format

1
{
2
  "code": "too_many_requests",
3
  "message": "You have exceeded the rate limit (duration:1h/1h). Please try again 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
• 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