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 TypeRequests/MinuteNotes
API Key300Per user, shared by their keys
OAuth Token300Per user, shared by their OAuth tokens
Session (web)300Per user, shared by their browser sessions
Unauthenticated60Per 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:

HeaderDescription
X-RateLimit-LimitMaximum requests per window
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix 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-Remaining header 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.