WakaTime · Rate Limits

Wakatime Rate Limits

WakaTime enforces a single global rate limit on the WakaTime API v1 — under 10 requests per second on average over any 5-minute window. The limit is per-user (not per-API-key or per-IP), so the budget is shared across editor plugins, scripts, and OAuth-authenticated apps acting on behalf of the same WakaTime account. OAuth has additional limits on token issuance: a maximum of 8 active access tokens per user and at most 10 tokens issued per user per hour. Token lifetimes are 365 days for the authorization-code flow and 12 hours for the implicit flow. Bulk heartbeat submissions are capped at 25 heartbeats per request, and bulk external-duration submissions at 1,000 entries per request. There is no separate sandbox tier — all keys hit the same production limit.

Wakatime Rate Limits is the machine-readable rate-limit profile for WakaTime on the APIs.io network, conforming to the API Commons Rate Limits specification.

It captures 5 rate-limit definitions, measuring requests_per_second, items_per_request, tokens_per_hour, and concurrent_tokens.

The profile also includes 6 backoff/retry policies defined and response codes documented for throttled and quotaExceeded.

Tagged areas include Rate Limiting, Developer Productivity, Time Tracking, and OAuth 2.0.

5 Limits Throttle: 429 Quota: 429
Rate LimitingDeveloper ProductivityTime TrackingOAuth 2.0

Limits

Global request budget (per user) user
requests_per_second · second
10
Averaged over any 5-minute window. Bursts above 10 rps are tolerated as long as the 5-minute average stays below the threshold.
Heartbeats bulk batch size request
items_per_request · request
25
Maximum heartbeats per POST /users/current/heartbeats.bulk call. Larger batches are rejected.
External durations bulk batch size request
items_per_request · request
1000
Maximum external durations per POST /users/current/external_durations.bulk call.
OAuth tokens issued per user user
tokens_per_hour · hour
10
Caps how often a single user can request new OAuth tokens.
OAuth active tokens per user user
concurrent_tokens
8
Beyond 8 active tokens, issuing a new token invalidates the oldest. Revoke tokens explicitly via POST /oauth/revoke when no longer needed.

Policies

per-user-budget
The 10-rps-over-5-minutes budget is scoped to the WakaTime user, not the API key or IP. Multiple editor plugins, CLIs, and OAuth apps acting for the same user share one budget — so heavy script users should consolidate calls.
bulk-endpoints
Use POST /users/current/heartbeats.bulk (max 25 heartbeats per call) and POST /users/current/external_durations.bulk (max 1,000 entries per call) to amortize the per-request limit across many records.
stats-eventual-consistency
Stats endpoints may return 202 Accepted while WakaTime calculates results in the background. Re-request after a short delay (60s+) rather than tight polling.
oauth-token-issuance
OAuth token issuance is capped at 10 per user per hour with a maximum of 8 concurrently active tokens. Revoke unused tokens via POST /oauth/revoke instead of issuing new ones.
exponential-backoff
On 429 responses, back off exponentially and retry the same request body unchanged. Heartbeat ingestion is idempotent on (entity, type, time, user_id), so re-sending the same heartbeat is safe.
never-call-from-public-site
WakaTime explicitly recommends NOT calling the API from a public website (other than the embeddable charts endpoint), since doing so exposes the API key and competes with the user's own plugins for the shared rate budget.

Sources