Contextualized Embeddings endpoint (/v1/contextualizedembeddings) rate-limits per chunk instead of per request

Bug Reports
,
1

Pre-flight checklist

  • This is about the Perplexity API, not the Perplexity app, Computer, Comet, or web UI.
  • I have removed API keys, secrets, and private data.
  • I have included enough information for someone else to reproduce the issue.

Bug type

  • Error response or failed request
  • Incorrect or unexpected model output
  • Missing, invalid, or stale citations/search results
  • Streaming issue
  • Structured output or JSON schema issue
  • SDK issue
  • Billing, credits, or rate limit issue
  • Dashboard, API key, or auth issue
  • Other API bug

Affected API area

  • Agent API
  • Search API
  • Sonar API
  • Embeddings API
  • SDKs
  • Dashboard, API keys, or auth
  • Billing or credits
  • Not sure

Summary

The x-ratelimit-used value (and effectively x-ratelimit-remaining) is decremented per chunk sent in the request, not per request. The docs advertise this endpoint’s limit as a QPS (requests-per-second) figure, and the sibling standard endpoint (/v1/embeddings) correctly counts 1 unit per request regardless of how many texts are in it — this endpoint does not.

Expected behavior

A single request to /v1/contextualizedembeddings should consume exactly 1 unit against the account’s rate limit (x-ratelimit-used should increment by 1), regardless of how many documents/chunks are included in the input array — matching both the documented QPS (requests-per-second) framing of this endpoint’s rate limit, and the behavior already correctly implemented on the sibling /v1/embeddings endpoint (confirmed: a 387-text request there consumes exactly 1 unit, not 387).

Actual behavior

Instead, x-ratelimit-used currently increments by the total chunk count in the request (3, 129, and 387 all reproduced exactly), so the account’s QPS quota is consumed per-chunk instead of per-request.

Minimal reproduction

  1. Note account’s published limit for this endpoint: x-ratelimit-limit: 835 (Tier 1-3).
  2. Send POST https://api.perplexity.ai/v1/contextualizedembeddings with a payload of 9 documents × 43 chunks each = 387 chunks, in 1 request:
    {
    “model”: “pplx-embed-context-v1-4b”,
    “input”: [ /* 9 arrays, 43 strings each, 387 total strings */ ],
    “dimensions”: 2560,
    “encoding_format”: “base64_int8”
    }
  3. Response headers show x-ratelimit-used: 387 for that single request — 46% of the entire 835 quota consumed by 1 of the ~835 requests/sec the limit should allow.
  4. Send 2 more such requests back-to-back (3 requests total, 1,161 chunks, well under 835×3=2,505 if counted correctly per-request). The 3rd request returns HTTP 429 (request_rate_limit_exceeded), because the account’s real per-window budget of 835 has already been consumed by ~2 requests, not the ~835 requests the documented QPS implies.

Response or error

Expected: at 835 QPS, sending 3 requests in quick succession should not come close to the limit. Actual: 3 requests of realistic size (9 docs/43 chunks — well within the documented 512-doc/16,000-chunk per-request caps) exhausts the quota and triggers 429s, because each request is being charged its chunk count instead of 1.

Request details

  • Endpoint: POST https://api.perplexity.ai/v1/contextualizedembeddings
  • Model or preset: pplx-embed-context-v1-4b
  • SDK/language/version: Raw HTTP via Python requests (no SDK)
  • Request ID: 8e0fb890-1eee-4fde-b1df-aeb3d30ee83c
  • Approximate time and timezone: 2026-09-23 20:39:42 GMT (unix 1790195983)
  • Consistent or intermittent: consistent

Additional context

2

Hello @dbrickner ,

Thank you for your post. The contextualized embeddings model is working as expected, but the docs needed an update. Instead of QPS it should have said “Chunks per Second”. I updated the docs to reflect the correct behavior. I appreciate you finding this.

Andrew