Developers

Rate limits

Limits are counted per key or connection, not per account, so one busy integration cannot slow down another. Go over and the API answers 429 with Retry-After.

The limits

WhatLimitCounted per
Reviews API (/api/v1)120 requests a minuteSecret key or OAuth connection
Adding reviews (POST /v1/companies/{company}/reviews)60 a minute and 1,000 a day, on top of the aboveSecret key or OAuth connection
Public reviews API (/v1/public/*)600 requests a minutePublishable key
Review feeds (/feeds/{key}/...)120 requests a minutePublishable key
OAuth token and revoke (/mcp/oauth/token, /revoke)120 a minuteIP address and client
OAuth sign-in (/mcp/oauth/authorize)60 a minuteIP address
OAuth client registration (/mcp/oauth/register)30 an hourIP address
Reviews MCP tool calls240 every 10 minutes per connection, and 960 per user across all of their connectionsAPI key or connected AI app, and user

Answers served from a conditional request (304 Not Modified) still count. AI reply drafts also have a monthly ceiling; reaching it answers 429 without Retry-After until the next month.

Headers

HeaderSent onMeaning
X-RateLimit-LimitReviews API and public reviews API answersRequests allowed in the current minute
X-RateLimit-RemainingReviews API and public reviews API answersRequests left in the current minute
Retry-AfterEvery rate-limit 429 (except the monthly AI draft ceiling)Seconds to wait before the next try
X-RateLimit-ResetReviews API 429 answersWhen the window resets, as Unix seconds (not readable from browser JavaScript; use Retry-After)
429 Too Many Requests
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 17
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1795075217

{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too many requests from this API key or app connection. Try again in 17 seconds."
}

Back off and retry

On 429, wait the Retry-After seconds and try again. On 500, 502 and 503, retry with an exponential backoff (1, 2, 4, 8 seconds...). Give up after a few tries and log the X-Request-Id.

Retry after 429 and 5xx
# curl 7.66 or later waits for Retry-After before each retry
curl --retry 5 https://app.grades.com/api/v1/companies \
  -H "Authorization: Bearer $GRADES_API_KEY"
  • Spread bulk work: 120 a minute is two requests a second. Use limit=100 on lists instead of many small pages.
  • Prefer webhooks to polling for new reviews; send If-None-Match when you do poll.
  • Contact us if your integration needs a higher limit.