Rate Limits & Quotas

TrackSERPs uses Redis token buckets to enforce per-minute rate limits and monthly request quotas based on your subscription tier.

Plan Tier Allowances

The table below reflects current API rate limits and monthly call allowances across subscription plans:

Plan	API Access	Active Keys	Requests / Min (per key)	Calls / Month	Webhooks	Alert Rules
Starter	Read Only	1	60 / min	10,000	0	5
Growth	Read + Write	3	120 / min	100,000	2	25
Pro	Read + Write	10	300 / min	500,000	5	100
Agency	Read + Write	25	600 / min	2,000,000	20	500

Accounts without an active plan: Accounts with no active subscription are barred from the API (403 plan_required). However, accounts holding a positive pay-as-you-go credit balance receive Starter-tier limits.

Rate Limit Response Headers

Every API response includes real-time rate limit tracking headers:

Header	Type	Description
`X-RateLimit-Limit`	Integer	The maximum allowed requests per minute for this API key.
`X-RateLimit-Remaining`	Integer	Remaining requests permitted in the current 60-second window.
`X-RateLimit-Reset`	Unix Timestamp	UTC seconds when the current 60-second window resets.
`Retry-After`	Integer	Sent on `429` responses. Number of seconds to wait before retrying.

Handling Rate Limit Responses (429)

When you exceed your per-minute token bucket, the API returns HTTP 429 Too Many Requests with code rate_limited:

429 Rate Limited Response

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 45
X-Request-Id: req_88301abcd

{
  "error": {
    "code": "rate_limited",
    "message": "API rate limit exceeded. Please slow down your requests.",
    "request_id": "req_88301abcd"
  }
}

Monthly Quotas & Heavy Endpoints

Monthly Call Allowance: When your account exhausts its monthly allowance, requests receive 429 quota_exceeded until the next billing rollover.
Heavy Endpoints: Bulk history lookups (GET /projects/:id/rankings/history) process up to 400 days of data and count as 5 requests toward rate limits and monthly quotas.
Failed Authentication Shield: If an IP address registers 20 failed authentication attempts within one minute, all requests from that IP are temporarily throttled for 5 minutes.
Write Limits: Upserting keywords allows up to 500 keywords per request. Manual check runs are limited to 1 run per project per hour and 10 run requests per key per hour.