Skip to main content

​
How Quotas Work

Fetchin uses a quota system to track your API usage. Each API request consumes one credit from your credit balance, unless the endpoint’s own reference page states otherwise. There are three exceptions among the endpoints below: /post/engagement, which returns comments and reactions together and bills 2 credits, all or nothing; /profile called with fullProfile=true, which reads two more pages of the profile and bills 2 credits, or 1 only when neither extra page could be read; and /company/batch, which bills 1 credit per company it returns. Credits reach that balance two ways: the monthly allowance of a subscription, and pay-as-you-go credits you buy outright. Every endpoint bills the same price whichever balance pays for it — see Your two balances.

​
Credit Counting

Paginated endpoints charge per page you request, not per item returned — again unless the endpoint’s reference page says otherwise. On /posts/search that price is flat per call: the same 1 credit whether the page comes back with 50 results, 1, or none at all, because the search ran either way. The price an endpoint charges is always stated on its own page; the table above covers the endpoints listed in this documentation.

​
What is billed

  • ✅ Successful requests - the price of the endpoint, from the table above (or from that endpoint’s reference page, when it prices differently)
  • ⚠️ 404 not found - 1 credit, always 1 even on /post/engagement
  • ✅ Every other failure (400, 401, 403, 410, 429, 402, 5xx) - free
  • 🔄 Quota renewal - happens automatically on your renewal date
A 404 is the one failing response that costs a credit, and confirming an absence costs more than returning a record rather than less. A success answers on the first attempt; an absence is only concluded once two independent sessions agree, across up to ten attempts, so a login wall is never reported to you as a missing record.Accounts created from 27 August 2026 onwards are charged from their first request. Accounts that existed before then are not charged for 404s until 1 October 2026.
Nothing else billable exists. Authentication errors, validation errors, rate limiting, running out of credits and any failure on our side are all free. Full breakdown at fetchin.io/pricing/credits.

​
Available Plans

Free

1,000 credits, onceGranted when the account is created
  • No card required
  • 5 requests per second
  • A one-time grant, not a monthly allowance

Subscription

From $50/mo for 50,000 creditsUp to 2,000,000 credits a month, self-serve
  • Renews monthly, cancel anytime
  • 5 requests per second
  • From $1.00 per 1,000, falling with volume

Pay as you go

From $75 for 50,000 creditsA one-time purchase, no subscription needed
  • Valid 12 months
  • 5 requests per second
  • From $1.50 per 1,000

Dedicated

10 to 100+ requests per secondDedicated capacity, set up with our team
  • Custom volume and rate limit
  • Priority support and SLA on request
  • Contact sales
The free 1,000 credits are a one-time grant. They are added when the account is created and are never topped up again — once they are spent, a subscription or a pay-as-you-go purchase is what puts credits back on the account. Only a paid subscription renews, and only 5 requests per second is self-serve: more throughput is provisioned with us.
Current prices for both ways of buying are at fetchin.io/pricing, and the configurator at fetchin.io/billing prices either one against the same volume.

​
Your Two Balances

Requests spend plan credits first, then pay-as-you-go, soonest expiry first. The order is fixed and there is no setting to change it — it is also the order that wastes the least, since plan credits are the ones that disappear at renewal. Both balances answer the same requests, so nothing in your integration changes when you buy: no new key, no new endpoint, no parameter. Buying does not raise your per-second rate limit either — that stays a property of your plan. See Rate Limits.

​
Monitoring Your Quota

​
Dashboard

Your dashboard shows real-time quota information:
  • Credits Remaining - How many credits you have left, both balances together
  • Plan Limit - Your monthly subscription allowance (one-time credits are not part of it)
  • Pay as you go - What is left of your one-time purchases, and when the next batch expires
  • RPS Limit - Your requests per second limit
  • Renewal Date - When a subscription’s allowance resets (a free account has none)
  • Usage Chart - Daily breakdown of your usage
  • Usage report - Requests, billable requests and credits used, per endpoint and per UTC day, for any month or date range, downloadable as CSV

​
Checking Quota Programmatically

Call GET /api/v1/subscription to read your quota from code. It returns the same figures the dashboard shows, and it does not consume credits.
creditsRemaining is what you can actually spend: the sum of both balances. The two that make it up are broken out next to it — subscriptionCreditsRemaining for the plan and paygCreditsRemaining for your one-time credits — with paygExpiresAt giving the date your soonest-expiring batch lapses (null when you hold none). creditsLimit and creditsUsed describe the plan alone, so creditsUsed stays a truthful “how much of my plan have I burned this month” even after a purchase, and creditsLimit is not a ceiling on creditsRemaining — a pay-as-you-go balance can put you above it. Use creditsRemaining to back off before you hit 402, and renewalDate to know when the plan allowance resets. active reflects billing standing only, so check both: a subscription can be active with zero credits left, and an account with no subscription at all reads status: "free" while still holding a live pay-as-you-go balance and being perfectly able to call the API.
This endpoint is free and is not gated on your quota, so it keeps answering after you have been blocked with 402. When a request fails on quota, call it to find out whether you are out of credits or whether billing needs attention. Your per-second rate limit still applies.
Poll this on a schedule rather than before every request. Usage is counted in memory and written back every 30 seconds, so creditsRemaining can lag your real consumption by up to that much during a burst. Leave yourself that much headroom rather than pacing right up to the last credit.

​
Consumption Over a Date Range

GET /api/v1/usage returns what you used between two UTC days — requests, billable requests and credits used, in total, per endpoint and per day — together with your balance now. It is free too, and it is the API side of the dashboard’s usage report: both count the same way.

​
Quota Management

​
What Happens When You Run Out?

A 402 Payment Required with code: "QUOTA_EXHAUSTED" normally means both balances are empty: your plan allowance for this period is spent and you hold no live pay-as-you-go credits. A pay-as-you-go balance keeps your requests flowing even after the plan allowance is gone. One nuance: a request that can cost more than one credit is checked against its full price before it runs, so a balance that is positive but smaller than that price is also a 402. With 1 credit left, for example, /post/engagement and /profile with fullProfile=true are refused while a standard /profile call still goes through. Where an endpoint works that way, its reference page says so; where that page also documents a creditsNeeded field, the details object carries what the request would have cost. Either way, read creditsRemaining rather than assuming a non-zero balance always clears. This is distinct from a 429 Too Many Requests (code: "RATE_LIMITED"), which is per-second throttling — the HTTP status alone tells them apart:
The error string and the code are unchanged — branch on code, never on the text. details is additive context showing which balance ran out and where to top up; read it for diagnostics and logs, but do not make your integration depend on a field of it being present.

​
Options When Quota Is Exceeded

1

Buy pay-as-you-go credits

Self-serve from Billing, in minutes and without talking to anyone, from $75 for 50,000 credits. They land on your account as soon as the payment clears, and calls resume with no code change. See Pay as you go.
2

Wait for renewal

A subscription’s allowance resets automatically on its renewal date (shown in the dashboard, and returned as renewalDate). The free credits granted at sign-up do not reset, so this step only applies if you subscribe.
3

Take or upgrade a subscription

If you are out every month, a subscription is cheaper per credit than repeat one-time purchases — and it is the only thing that also raises your requests-per-second limit above 5. Self-serve up to 2,000,000 credits a month at fetchin.io/billing; above that, or for more throughput, contact sales.

​
Pay As You Go

A one-time purchase of credits, bought self-serve from Billing. No monthly commitment and no subscription required — it works on its own, alongside a plan, or on top of a dedicated contract. Rates are progressive, so buying more lowers the price of the credits above each threshold rather than repricing the whole purchase. The configurator always shows the exact total and the effective per-1,000 rate before you pay. Pay as you go → — full rate table, worked examples, and how expiry works when you hold several purchases.

​
Best Practices

Store API responses locally to avoid redundant requests for the same data.
Use exponential backoff for failed requests instead of immediately retrying.
Check your dashboard regularly to track usage patterns and avoid surprises.
Quota exhaustion is 402 with code: "QUOTA_EXHAUSTED", it means both your plan and your pay-as-you-go credits are empty, and retrying will not clear it — buying credits or waiting for renewal will. Handle it separately from 429 (RATE_LIMITED), which is per-second throttling and is worth retrying after a short backoff.

​
Quota Reset Schedule

A subscription’s allowance resets monthly on its own renewal date — the anniversary of the subscription, not of the account:
  • Subscribed on January 15 → Resets on the 15th of each month
  • Subscribed on March 31 → Resets on the last day of each month
  • Time zone: UTC
Unused plan credits do NOT carry over to the next month. The reset replaces your allowance, it does not add to it: whatever is left of the month’s credits on your renewal date is gone.Pay-as-you-go credits are the exception. They are not touched by a renewal and stay on your account for 12 months from their own purchase date — see Pay as you go.
The free credits granted at sign-up have no reset at all. They are a one-time grant, so an account that has never subscribed keeps whatever is left of its 1,000 credits and nothing is added on any date. The renewalDate such an account carries renews nothing; read creditsRemaining instead.