Skip to main content

​
Rate Limits & Tiers

The Influship API uses -based rate limiting. Each request consumes part of your per-minute and per-hour budget based on the credit cost of that operation.

​
How Limits Work

Two windows are enforced for every API key:
WindowPurposeFree tier budget
Per minutePrevent short spikes150 credits
Per hourPrevent sustained overuse1,500 credits
Heavier endpoints use more of that budget than lighter ones. A search with limit: 10 consumes roughly 45 credits of budget, while an autocomplete call consumes 0.05. This means you can make thousands of autocomplete requests in the time it takes to exhaust the budget on a few dozen searches.
See Pricing for the full credit cost table.

​
Trust Tiers

increase your rate limits as your account matures. They’re based on lifetime spend — not monthly spend — and they never downgrade. A slow month doesn’t reduce your limits.
TierCredits/minCredits/hourBilling thresholdHow to reach
free1501,500$5Signup
tier_17507,500$25First successful payment
tier_23,00030,000$100$500 lifetime spend
tier_315,000150,000$250$2,000 lifetime spend
enterprisecustomcustomcustomContact us
Tiers affect rate limits and billing thresholds only. They do not change endpoint prices — a search costs the same credits on the free tier as on Tier 3.

​
How Billing Thresholds Work

Stripe creates an invoice when your accumulated usage reaches your tier’s billing threshold. On the free tier, that’s $5. After your first successful payment, you move to Tier 1 and the threshold increases to $25. This means you’re invoiced less frequently as your account matures.

​
Checking Your Current Tier

Every response includes the X-Billing-Plan header with your current tier code: 
X-Billing-Plan: tier_1

​
Response Headers

Every successful response includes your current rate limit state:
HeaderDescription
RateLimit-Limit-MinuteCredits allowed in the current minute window
RateLimit-Remaining-MinuteCredits left in the current minute window
RateLimit-Reset-MinuteUnix timestamp when the minute window resets
RateLimit-Limit-HourCredits allowed in the current hour window
RateLimit-Remaining-HourCredits left in the current hour window
RateLimit-Reset-HourUnix timestamp when the hour window resets
X-Billing-PlanCurrent trust tier code
Example after a search on the free tier: 
RateLimit-Limit-Minute: 150
RateLimit-Remaining-Minute: 105
RateLimit-Reset-Minute: 1703571600
RateLimit-Limit-Hour: 1500
RateLimit-Remaining-Hour: 1455
RateLimit-Reset-Hour: 1703575200
X-Billing-Plan: free
Monitor RateLimit-Remaining-Minute and RateLimit-Remaining-Hour if you’re running batch operations. When either hits zero, the next request gets a 429.

​
What Happens at the Limit

There’s no warning before you hit a rate limit — the API doesn’t send a “you’re close” signal. When a request would push usage above either the minute or hour budget, it’s rejected with a 429 immediately. The request is not charged. This means for production integrations, you should track the remaining budget headers proactively rather than waiting for a 429.

​
429 Rate Limit Exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded (per minute)",
    "status_code": 429
  }
}
How to handle it:
  1. Check the Retry-After header if present — it tells you how many seconds to wait
  2. Otherwise, read RateLimit-Reset-Minute or RateLimit-Reset-Hour for the next window
  3. Implement exponential backoff: wait 2^attempt seconds, capped at 60s, with jitter
  4. If this happens regularly, reduce concurrency or increase your tier

​
402 Payment Required

{
  "error": {
    "code": "payment_required",
    "message": "Payment required to continue API access",
    "status_code": 402
  }
}
This means billing is suspended — usually because Stripe couldn’t collect a threshold invoice. Don’t retry 402 automatically; it needs human intervention:
  1. Check the dashboard for outstanding invoices
  2. Update your payment method if needed
  3. Pay the invoice
  4. Access resumes immediately after payment

​
Good Practices

  • Monitor your budget headers. Log RateLimit-Remaining-Minute and RateLimit-Remaining-Hour on every response. Set alerts before they hit zero.
  • Keep search limit tight. A limit: 25 search consumes 75 credits of your minute budget. Five of those in quick succession can exhaust a free-tier minute window.
  • Batch known work. POST /v1/profiles/lookup resolves multiple profiles in one request with minimal rate-limit impact, compared to calling GET /v1/profiles/{platform}/{username} in a loop.
  • Treat 429 and 402 differently. 429 is a throttle — back off and retry. 402 is a billing issue — surface it to your ops team and stop retrying.
  • Budget for the free tier. On the free tier, you can run roughly 3 searches per minute (at limit: 10) or ~33 per hour. That’s enough for prototyping but not for a production integration with real traffic. Upgrade early.