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: Statsig
providerId: statsig
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.
# 2026-09-17: re-read against the live Console API docs and confirmed. Also probed the live
# API for runtime rate-limit signalling and found none. Upgraded generated -> searched.
method: searched
source: https://docs.statsig.com/console-api/introduction
verified: '2026-09-17'
verified_status: 200
limit_count: 5
modified: '2026-09-17'
reconciled: true
tags:
  - Rate Limiting
  - Feature Flags
  - Experimentation
  - Console API
description: Statsig publishes rate limits on the Console API for mutation requests, throttled per project.
  Mutation calls are bounded by both a short-window (~100 requests / 10 seconds) and a longer-window
  (~900 requests / 15 minutes) ceiling; over-limit responses return HTTP 429. Read-side flag and config
  evaluations on the SDK / HTTP APIs are not published as numeric per-second limits and are governed by
  fair-use against the project's metered-event entitlement.
sources:
  - https://docs.statsig.com/console-api/introduction
  - https://www.statsig.com/pricing
responseCodes:
  throttled: 429
  quotaExceeded: 429
responseHeaders:
  rate_limit_headers: none
  retry_after: false
  observed: [cache-control, referrer-policy, x-content-type-options, x-statsig-region, via, alt-svc]
  probe:
    url: https://statsigapi.net/console/v1/gates
    method: GET with an invalid Console key
    http_status: 401
    date: '2026-09-17'
  note: >-
    Probed live. Statsig returns no X-RateLimit-*, no RateLimit-* (RFC 9238 draft) and no
    Retry-After, and declares no 429 on any of the 324 operations in its published OpenAPI.
    The published ceilings below are therefore documentation only — an agent cannot pace itself
    from the response, it can only fail and guess. This is the single highest-value runtime fix
    available to Statsig.
declaredInSpec: false
limits:
  - name: Segment ID-list write (Add IDs to Segment)
    scope: endpoint
    metric: requests_per_15_minutes
    limit: 900
    timeFrame: minute
    endpoint: PATCH /console/v1/segments/{id}/id_list
    notes: >-
      Documented per-endpoint on the operation's own reference page as "900 requests /15m or
      12 requests /10s" — a tighter short-window ceiling than the global mutation limit.
  - name: Segment ID-list read (Get IDs in a Segment)
    scope: endpoint
    metric: requests_per_10_seconds
    limit: 100
    timeFrame: second
    endpoint: GET /console/v1/segments/{id}/id_list
    notes: Documented per-endpoint; the only read operation with a published numeric limit.
  - name: Console API mutations (short window)
    scope: project
    metric: requests_per_10_seconds
    limit: 100
    timeFrame: second
    notes: Approximately 100 mutation requests per 10 seconds, per project. 429 returned on breach.
  - name: Console API mutations (long window)
    scope: project
    metric: requests_per_15_minutes
    limit: 900
    timeFrame: minute
    notes: Approximately 900 mutation requests per 15 minutes, per project. 429 returned on breach.
  - name: Flag and config evaluations (SDK / HTTP API)
    scope: project
    metric: varies
    limit: 'unlimited under fair use; metered against monthly event entitlement'
    notes: No published numeric per-second cap; capacity is bounded by the plan's metered-event allowance.
policies:
  - name: Per-Project Scoping
    description: Console API throttles are calculated per project rather than per API key, so concurrent
      keys for the same project share the budget.
  - name: Mutation vs Read
    description: Documented numeric limits apply to mutation (write) endpoints on the Console API. Read-only
      evaluation traffic is governed by event quotas in the plan, not request-rate ceilings.
  - name: API Versioning
    description: Clients should send STATSIG-API-VERSION (e.g. 20240601) to pin behavior; STATSIG-API-KEY
      authenticates requests against the project budget.
  - name: Backoff
    description: On 429, clients should back off and retry with jitter; aggregate writes from a single
      project to avoid bursts that cross the 10-second window.
maintainers: []