Rate limits

ProteinIQ uses several controls for public API usage. Request rate limits protect the API, while credits and job concurrency control compute usage.

Account endpoint

Use GET /api/v1/account with jobs:read to inspect the current API key workspace, credits, active job count, concurrency limit, public API rate-limit policy, and key metadata.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $PROTEINIQ_API_KEY" \
  "https://proteiniq.io/api/v1/account"

Abbreviated example response with illustrative credit and concurrency values. COMMERCIAL_TEAM is the current API tier identifier for Enterprise:

{
  "object": "account",
  "workspace": {
    "id": "team_123",
    "plan": {
      "tier": "COMMERCIAL_TEAM",
      "paid": true
    },
    "credits": {
      "available": 500
    }
  },
  "limits": {
    "active_jobs": 1,
    "concurrent_jobs": {
      "max": 3,
      "remaining": 2
    },
    "public_api_rate_limit": {
      "limit": 120,
      "window_seconds": 60
    }
  },
  "api_key": {
    "id": "key_123",
    "env": "LIVE",
    "prefix": "pq_live_abc123",
    "scopes": ["jobs:read", "jobs:write", "files:read", "files:write", "projects:read", "projects:write"]
  }
}

Request rate limits

Public API routes are rate limited. Rate-limit failures return rate_limited and may include retry headers.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests"
  }
}

When headers are present, use them to schedule retries:

• X-RateLimit-Limit: Current request limit
• X-RateLimit-Remaining: Remaining requests in the current window
• X-RateLimit-Reset: ISO 8601 timestamp for the next reset
• Retry-After: Suggested seconds to wait before retrying

The current per-key policy is 120 requests per 60 seconds. A separate pre-authentication IP limit can also apply. Status polling, result fetches, tool reads, and other public API requests share this budget for the API key.

Job status and result polling also have per-job throttles. For a single API key and job, call GET /api/v1/jobs/{jobId}/status no more than once every 5 seconds. The result endpoint uses the same 5 second per-job pace to protect stored outputs and signed file URL generation.

Polling and backoff

Polling should be paced by job state, not by a fixed sub-second interval. Start status polling at 5 seconds, double the delay after each non-terminal response, and cap the delay at 30 seconds. Add a small random jitter before each poll.

Use delays of 5, 10, 20, and then 30 seconds between polls. A Retry-After value takes precedence even when it exceeds the 30-second backoff cap.

Clients that poll every 0.5 seconds can use the full public API quota on one job and may be throttled by the per-job polling limit. That leaves no room for result fetches, list calls, retries, or other jobs. Use server-sent events when you need live status updates.

Credits

Paid jobs require enough workspace credits for the fixed charge or initial time-based authorization. Quote the job to inspect available_credits, billable_credits, and blocking_errors before submission.

A quote does not reserve credits. Other jobs can spend the balance before a new submission is accepted. Time-based jobs can also request further authorization while they run, subject to their spending limit.

Concurrent jobs

Workspaces have a maximum number of active concurrent jobs. GET /api/v1/account returns the current active count and remaining concurrency.

If the workspace already has too many active jobs, submission can return concurrent_job_limit_exceeded.

Retry behavior

• Rate limit reached: Wait until the reset time before retrying.
• Job still running: Continue polling status with exponential backoff, or use the events endpoint.
• Result not ready: Respect the Retry-After header before fetching results again.
• Concurrent job limit reached: Wait until an active job finishes, then submit again.
• Insufficient credits: Add credits or lower job size before retrying.
• Unknown submission result: Retry with the same Idempotency-Key to avoid duplicate jobs.