Rate Limits
Understand and work within Velocity GraphQL API rate limits.
Limits by Auth Type
GraphQL GET and POST requests share a sliding window budget per verified user and authentication type. Users on the same network have independent authenticated budgets. Refreshing a token, creating another key, switching workspaces or changing networks does not reset your budget.
| Auth Type | Requests/Minute | Notes |
|---|---|---|
| API Key | 300 | Per user, shared by their keys |
| OAuth Token | 300 | Per user, shared by their OAuth tokens |
| Session (web) | 300 | Per user, shared by their browser sessions |
| Unauthenticated | 60 | Per IP address |
Invalid or revoked credentials use the unauthenticated IP budget. A separate ceiling of 3,000 requests per minute per IP protects authentication work before credentials are verified. Other API endpoints may have their own limits.
External-service REST API
The external-service OAuth API shares a separate 300 requests/minute user budget across its REST identity and issue endpoints. Issue requests also consume the GraphQL OAuth budget because they execute the same guarded GraphQL operations. A REST rate-limit response returns HTTP 429 with Retry-After; issue responses also forward the GraphQL rate-limit headers when available. Reconnecting an app or selecting a different workspace does not create a new budget.
MCP
/api/mcp GET and POST requests share a separate 300 requests/minute budget per bearer token. Requests without a vel_-prefixed token share an IP-based budget. HTTP 429 responses include Retry-After, X-RateLimit-Limitand X-RateLimit-Remaining. This is separate from GraphQL and the workspace event feed's connection limits.
These rate counters are held in memory per server instance; they are protective limits, not a guaranteed sustained throughput allowance.
Rate Limit Headers
GraphQL responses include rate limit headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per window |
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Reset | Unix timestamp when the oldest request leaves the window |
Exceeding the Limit
When you exceed the rate limit, the API returns a 429 Too Many Requests status with a Retry-After header indicating the minimum wait. The browser retries reads at most twice, waits at least that long, and stops waiting when the read is cancelled. A missing, invalid or greater-than-one-minute wait is shown as an error. Mutations are never replayed automatically. If a write loses its response, check whether it saved before submitting it again.
Best Practices
- Cache responses when possible to reduce API calls
- Use pagination to fetch data in smaller batches
- Batch related operations where the API supports it
- Monitor the
X-RateLimit-Remainingheader to pace requests - Use webhooks instead of polling for real-time updates
High-volume Integrations
Use cached reads, pagination and webhooks to keep requests within your budget. Contact support@velocity.quest to discuss high-volume requirements.