Rate Limits

The Virlo API enforces rate limits to ensure reliability for all users. Limits are applied per API key and vary by endpoint and HTTP method. Every response includes headers so your application always knows where it stands.

How Rate Limits Work

Rate limits use sliding time windows — each window tracks how many requests your API key has made to a given endpoint within that period. When you exceed a limit, the API returns 429 Too Many Requests until the window resets.

Limits are tracked per API key, not per IP address.
Different endpoints may have different limits.
GET and POST methods on the same endpoint are tracked separately.
Only requests that reach the rate limiter count — authentication failures (401) do not consume your rate limit budget.

Response Headers

Every successful response includes rate limit headers:

Name
X-RateLimit-Limit
Type
integer
Description
Maximum number of requests allowed in the current window.
Name
X-RateLimit-Remaining
Type
integer
Description
Requests remaining before the limit is reached.
Name
X-RateLimit-Reset
Type
integer
Description
Unix timestamp (seconds) when the current window resets.

When a request is rate limited, the response also includes:

Name
Retry-After
Type
integer
Description
Seconds until the window resets. Wait at least this long before retrying.

Default Rate Limits

All API keys share the same default limits. The table below shows the limits that apply to key endpoint groups.

Global

Window	Limit
Per day (24h)	10,000 requests

The global limit applies to any endpoint that does not have a more specific rule below.

Satellite — Creator Lookup

GET /v1/satellite/creator/:platform/:username

Window	Limit
Per minute	5 requests
Per hour	100 requests
Per day	1,000 requests

Tip: Use the batch endpoint (POST /v1/satellite/creators/batch) to look up up to 25 creators in a single request. Batch calls count as 1 request against your global limit, making them far more efficient for pipeline workloads.

Satellite — Status Polling

GET /v1/satellite/creator/status/:job_id

Status polling endpoints are tracked under the global limit (10,000/day), not the creator lookup limit. You can poll job status as frequently as needed without consuming satellite lookup quota.

Satellite — Video Outlier

POST /v1/satellite/video-outlier

Window	Limit
Per minute	5 requests
Per hour	100 requests
Per day	1,000 requests

Tracking Endpoints

All tracking endpoints — creator posts, posting cadence, post collection — use the global limit (10,000/day). These are lightweight database reads and are designed for high-throughput access.

Video Digest, Trends, Hashtags

Window	Limit
Per minute	50 requests
Per hour	500 requests
Per day	5,000 requests

Handling Rate Limits

When you receive a 429 response, the best approach is to wait and retry:

Read the Retry-After header to know exactly how long to wait.
Implement exponential backoff as a fallback if the header is missing.
For batch workloads, add a small delay (200-500ms) between sequential requests to stay well under per-minute limits.

429 Response

{
  "statusCode": 429,
  "message": "Rate limit exceeded",
  "error": "Too Many Requests",
  "limit": 5,
  "remaining": 0,
  "resetAt": 1713200400,
  "resetAtFormatted": "April 15th, 2026, 6:00 PM UTC",
  "retryAfter": 42
}

Best Practices for High-Volume Pipelines

If your integration processes many creators per run (e.g., 50-200 artists), follow these patterns to maximize throughput:

Use batch endpoints — POST /v1/satellite/creators/batch processes up to 25 creators per call. For 200 artists, that's just 8 API calls instead of 200.
Space status polls — When polling job results, wait 1-2 seconds between checks. Jobs typically complete in 10-30 seconds.
Parallelize reads — Tracking post lists, cadence analytics, and individual post lookups all use the generous global limit. You can safely fire these concurrently.
Cache completed results — Satellite lookup results are available for 24 hours. Fetch once, cache locally.

Need Higher Limits?

Default limits work well for most integrations. If your pipeline requires higher throughput — for example, processing hundreds of creators multiple times per day — we can configure custom limits for your account.

You can also reach us at [email protected] or book a call to discuss enterprise capacity planning.