specification: API Commons Rate Limits
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/RateLimits
provider: Sanity
providerId: sanity
created: '2026-05-04'
# Provenance stamped 2026-08-11: this artifact was written by the API Evangelist
# bulk sweep dated 2026-05-04, not harvested from the provider. See roadmap#35.
method: generated
modified: '2026-05-05'
reconciled: true
tags:
  - Rate Limiting
  - Headless CMS
  - Content Management
  - GROQ
  - Real-Time
description: Sanity rate limits apply to direct API calls only; cached responses served from the API
  CDN are not rate limited. Limits are enforced per-IP for request rate and per-dataset for concurrency.
  When limits are exceeded the API returns HTTP 429 and the docs recommend exponential backoff. Plan-level
  monthly quotas (CDN requests, direct API requests, bandwidth) are tracked separately in plans/.
sources:
  - https://www.sanity.io/docs/api-cdn
  - https://www.sanity.io/pricing
responseCodes:
  throttled: 429
  quotaExceeded: 429
limits:
  - name: API CDN cached responses
    scope: dataset
    metric: requests_per_second
    limit: 'cached responses are not rate limited'
    notes: Cache misses fall through to the direct API and incur the per-IP limits below.
  - name: Direct API general request rate (per IP)
    scope: IP
    metric: requests_per_second
    limit: 500
    timeFrame: second
  - name: Direct API mutations rate (per IP)
    scope: IP
    metric: requests_per_second
    limit: 25
    timeFrame: second
  - name: Direct API uploads rate (per IP)
    scope: IP
    metric: requests_per_second
    limit: 25
    timeFrame: second
  - name: Direct API query concurrency (per dataset)
    scope: dataset
    metric: concurrent_requests
    limit: 500
  - name: Direct API mutation concurrency (per dataset)
    scope: dataset
    metric: concurrent_requests
    limit: 100
policies:
  - name: Use the API CDN
    description: "Setting `useCdn: true` in the client serves cached responses that are not rate limited; this is the recommended default for read-heavy workloads."
  - name: Backoff on 429
    description: When the API returns 429 Too Many Requests, clients should implement exponential backoff
      with jitter or wait briefly before retrying.
  - name: Cache miss fallthrough
    description: API CDN cache misses are forwarded to the direct API and are subject to the per-IP and
      per-dataset concurrency limits.
  - name: Headers
    description: Sanity does not document X-RateLimit-* or Retry-After headers; consumers should rely
      on the 429 status and a backoff timer rather than header-driven scheduling.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com