specification: API Commons Rate Limits
specificationVersion: '0.1'
provider: Canvas
providerId: canvas
generated: '2026-09-05'
modified: '2026-09-05'
created: '2026-05-04'
method: searched
source: https://developerdocs.instructure.com/services/canvas/basics/file.throttling
docs:
- https://developerdocs.instructure.com/services/canvas/basics/file.throttling
- https://canvas.instructure.com/doc/api/file.throttling.html
description: Canvas throttles by COST, not by request count. Every request deducts a floating-point cost from a
  per-access-token quota that replenishes over time faster than real-time. Replaces the 2026-05-04 scaffold values,
  which were invented.
model: cost-quota (leaky bucket, replenishing)
limit_count: 1
limits:
- scope: per-access-token
  window: continuous (quota replenishes over time)
  limit: unpublished numeric quota — Canvas publishes the mechanism and the headers, not the ceiling
  burst: Parallel requests incur an additional pre-flight penalty which is credited back to the quota when each
    request finishes; only the real cost is retained. A client issuing no more than one simultaneous request is
    unlikely to be throttled.
  note: Each OAuth access token carries its own quota, so one user of an integration cannot throttle another.
  source: https://developerdocs.instructure.com/services/canvas/basics/file.throttling
headers:
- name: X-Request-Cost
  direction: response
  always: true
  meaning: Floating-point amount this request deducted from the remaining quota.
- name: X-Rate-Limit-Remaining
  direction: response
  always: false
  meaning: Remaining quota. Returned only when throttling applies to the request.
exhaustion:
  status: 429
  canvas_label: 429 Forbidden (Rate Limit Exceeded)
  note: Instructure's current throttling page states 429. Older copies of the same page (and the mirror at canvas.instructure.com/doc/api/file.throttling.html)
    state 403 Forbidden (Rate Limit Exceeded); self-hosted and older Canvas instances still return 403. Clients
    should treat BOTH as throttling.
  retry: Retry the request later. Canvas publishes no Retry-After header.
retry_after_header: false
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com