Skip to main content

Rate limits

The InstaVM API limits how fast you can call some endpoints and how many VMs you can run at once. Every limit answers 429 Too Many Requests. This page lists each limit, its scope, and how to retry. The numbers are today's values and can change; handle a 429 whenever it comes.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"detail":"Rate limit exceeded. Maximum 60 requests per minute allowed."}

Only one of these limits sends a Retry-After header; the table marks it. When a 429 has no Retry-After, back off exponentially.

Limits at a glance​

LimitScopeNumberRetry-After
Requests per minute, per accountYour account, all API keys togetherSet by your plan; 60 for an account with no active subscriptionNo
Requests per minute, per addressYour IP address, each endpoint separatelyPer endpoint, belowNo
Concurrent VMsYour accountSet by your planNo
Concurrent VM startupsYour accountSet by your plan; 1 on the Free plan by default15 seconds
VM boots per secondYour account3 per second by default; 5 on Pro and EnterpriseNo
Share linksYour IP address, across all share hosts20 per second, bursts of 200No

Two endpoints return your account's numbers:

  • GET /v1/users/me returns vm_usage with active_vms, max_concurrent_vms, remaining_slots and max_concurrent_vm_startups.
  • GET /v1/billing/plans returns api_rate_limit_per_minute and max_concurrent_vms for each plan.
curl https://api.instavm.io/v1/users/me \
-H "X-API-Key: $INSTAVM_API_KEY"

Requests per minute, per account​

These endpoints share one budget per account, across all of its API keys:

  • POST /v1/vms, POST /v1/vms/{vm_id}/clone
  • POST /v1/sessions/session
  • POST /execute, POST /execute_async
  • POST /upload, POST /download
  • POST /v1/snapshots, DELETE /v1/snapshots/{snapshot_id}
  • some tape and recording endpoints

The budget is your plan's api_rate_limit_per_minute. An account with no active or trialing subscription gets 60. The window slides: the API counts your calls to these endpoints over the last 60 seconds. A rejected call does not count.

{"detail": "Rate limit exceeded. Maximum 60 requests per minute allowed."}

Other endpoints do not count against this budget.

Requests per minute, per address​

Some endpoints also have a limit per client IP address, counted separately for each endpoint. The table shows today's limit for each.

EndpointPer minute
POST /v1/snapshots10
GET /v1/snapshots, GET /v1/snapshots/{snapshot_id}500
DELETE /v1/snapshots/{snapshot_id}30
POST /v1/shares10
PATCH /v1/shares/{share_id}30
POST /v1/egress/session/{session_id}, POST /v1/egress/vm/{vm_id}30
GET /v1/egress/session/{session_id}, GET /v1/egress/vm/{vm_id}120

Over the limit, the API answers:

{"detail": "Rate limit exceeded. Please try again later."}

Concurrent VMs​

Your plan sets how many VMs can be active at once (max_concurrent_vms). Suspended VMs do not count. The limit is checked whenever a request needs a new VM: POST /v1/vms, POST /v1/vms/{vm_id}/clone, POST /v1/sessions/session, and POST /execute, POST /execute_async, POST /upload or POST /download on a session that has no VM yet.

{"detail": "VM limit reached (5/5). Stop or suspend a VM, or upgrade your plan for more concurrent VMs. This request was not queued."}

POST /v1/sessions/session puts Cannot create session: in front of the same message.

Waiting does not clear this limit. Stop or suspend a VM, then retry.

Concurrent VM startups​

POST /v1/vms also limits how many creates can be in progress at once for your account (max_concurrent_vm_startups). By default this is 1 on the Free plan and 2 on other plans. Over it, the API answers 429 with Retry-After: 15:

{"detail": "Your plan allows one VM or Devbox startup at a time. Wait for the current startup to finish and check its status before retrying. This request was not queued."}

VM boots per second​

When POST /execute or POST /execute_async has to boot a new VM, the API limits how many it boots per second for your account. By default a request that gets a pre-booted VM does not count, and a session that starts from a snapshot always does. The default limit is 3 per second, and 5 per second on Pro and Enterprise plans.

{"detail": "VM spawn rate limit exceeded. Maximum 3 VM spawns per second allowed. Please wait before creating more VMs."}

Requests to share links (*.instavm.site) are limited per client IP address, across all share hosts: 20 requests per second, with bursts of up to 200. Over that, the proxy answers 429 before the request reaches the VM. The body is an HTML page, not JSON, and there is no Retry-After header.

Retrying a 429​

Wait, then retry with exponential backoff and some random jitter. Rejected requests do not use up your per-account budget, so short backoffs recover quickly. Do not retry a concurrent-VM 429 in a loop: it clears only when one of your VMs stops or suspends.

import random
import time

from instavm import InstaVM, RateLimitError

client = InstaVM("instavm_sk_...")

def with_backoff(call, attempts=5):
for attempt in range(attempts):
try:
return call()
except RateLimitError:
if attempt == attempts - 1:
raise
time.sleep(min(2 ** attempt, 30) + random.random())

vms = with_backoff(client.vms.list)

What the SDKs retry on their own​

Python SDK (0.26). max_retries defaults to 0: no retries. With max_retries=N, the SDK retries 5xx responses, timeouts and connection errors up to N times, waiting 1, 2, 4, ... seconds. It never retries 401, 403 or 429, and it does not read Retry-After. It retries every method, so a retried client.vms.create() can start a second VM and a retried execute() can run the command twice.

JavaScript SDK (0.17). maxRetries defaults to 3, and a value of 0 is also treated as 3. The SDK retries 429, 5xx, timeouts and connection errors, waiting retryDelay (default 1000 ms) doubled on each attempt, with jitter, up to 30 seconds. It retries every method, including VM creation and code execution. RateLimitError.retryAfter is the Retry-After header in seconds, or 60 when the response has none.

See Errors for which requests are safe to repeat.