Rate Limits

All API requests are rate limited per API key. Your rate limit depends on your plan. Rate limit information is included in every response via standard headers.

Plan	Requests per minute	How to access
Free / Pay As You Go	10	Default for all accounts
Starter Cached ($100/mo)	25	Cached data subscription
Growth Cached ($250/mo)	50	Cached data subscription
Scale Cached ($500/mo)	100	Cached data subscription
Enterprise Cached ($1,000/mo)	Unlimited	Cached data subscription

Response Headers

• RateLimit-Limit — Your current rate limit for this window
• RateLimit-Remaining — Requests remaining in the current window
• RateLimit-Reset — Seconds until the rate limit window resets

Handling Rate Limits (HTTP 429)

When you exceed your rate limit, the API returns HTTP 429 Too Many Requests. Best practice: check the RateLimit-Reset header and retry after that delay.

async function lookupWithRetry(entityName, state, apiKey) {
  const res = await fetch('https://api.opensosdata.com/v1/lookup', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({ entity_name: entityName, state: state })
  });

  if (res.status === 429) {
    const resetAfter = parseInt(res.headers.get('RateLimit-Reset') || '60');
    console.log('Rate limited, retrying in ' + resetAfter + 's');
    await new Promise(r => setTimeout(r, resetAfter * 1000));
    return lookupWithRetry(entityName, state, apiKey);
  }

  return res.json();
}

Need Higher Limits?

Upgrade to a cached data subscription for higher rate limits and lower per-lookup costs.

Timeouts

Each lookup has a server-side deadline that limits how long the scraper runs:

Scenario	Deadline
Standard states	60 seconds
States requiring captcha solving	120 seconds

Certain states require captcha solving and receive the longer deadline. Check GET /v1/health/status for per-state details.

The deadline covers scraping only. Under load, a request may wait to be dispatched before the deadline clock starts, so total response time can exceed the deadline.

Observed Response Times

Over the last 14 days (n = 66,062):

Class	p50	p95	p99	Max
Standard states	58 s	175 s	296 s	585 s
Captcha states	71 s	241 s	360 s	713 s

Requests that take longer than roughly 200 seconds succeed less than half the time. Past 350 seconds, fewer than 12% return a billable result. Most long-running requests are infrastructure failures, not slow scrapes.

Client Timeout

There is no client-supplied timeout parameter. The server deadline is fixed. Set your HTTP client timeout to at least 300 seconds for standard states and 360 seconds for captcha states to avoid aborting requests that would have succeeded (these values sit at or above p99). A shorter timeout is a valid tradeoff—most requests past 200 seconds fail anyway—but will occasionally discard a paid result.