Get subscription and quota status

Return the authenticated account's current subscription state: plan, remaining/used/total credits, per-second rate limit (RPS), renewal date, and whether the subscription is active (in good standing) or affected by a non-payment or scheduled cancellation. Use it to programmatically confirm access before routing traffic. This endpoint is free — it does not consume credits — and returns a 200 even when your quota is exhausted (so you can detect exactly why calls are failing). Credits come from two balances - the monthly plan allowance and any pay-as-you-go credits bought outright (valid 12 months from purchase) - and creditsRemaining is their sum, broken out by subscriptionCreditsRemaining and paygCreditsRemaining. Values reflect our billing store and may lag real-time usage by a few seconds. Treat creditsRemaining > 0 as "can I call the API right now?" - a pay-as-you-go-only account has no subscription and reports status: "free" with active: false while still being able to call every endpoint. This endpoint is also metered on its OWN budget of 1 request per second per account, counted separately from your plan's per-second limit: polling it never consumes plan RPS (it returns X-RateLimit-Cost: 0), and a 429 here means you exceeded 1 req/s on this endpoint alone, not that your plan budget is spent. Because the call spends none of the plan window it does not report it, so this response carries no X-RateLimit-Remaining or X-RateLimit-Reset; X-RateLimit-Limit still shows your plan's RPS.

get/api/v1/subscription

Request

  • Base URL: https://api.fetchin.io
  • URL: https://api.fetchin.io/api/v1/subscription
  • Auth: API key in header X-API-Key

Response

Current subscription and quota status

planstring required

Plan identifier (e.g. "free", "custom").

activeboolean required

Whether the subscription is in good standing. False when the billing status is past_due, incomplete, canceled or unpaid. Note: a false value here means a billing issue; check creditsRemaining separately to know if you still have credits.

status'active' | 'free' | 'trialing' | 'past_due' | 'incomplete' | 'unpaid' | 'canceled' required

Raw billing status. Branch on this rather than the HTTP status. free and active are good standing; past_due/incomplete/unpaid indicate a payment problem; canceled means the subscription has ended.

creditsRemaininginteger required

Total credits you can still spend: the plan allowance left for the current billing period PLUS your pay-as-you-go credits. This is the figure to gate traffic on. It can exceed creditsLimit, since pay-as-you-go credits are not part of the plan allowance.

subscriptionCreditsRemaininginteger

Optional. The plan half of creditsRemaining: credits left in the current billing period, which are discarded at renewal. Spent before pay-as-you-go credits.

paygCreditsRemaininginteger

Optional. The pay-as-you-go half of creditsRemaining: credits left across every one-time purchase you hold. Spent after the plan allowance, soonest-expiring first. 0 when you hold none.

paygExpiresAtstring date-time nullable

Optional. When your soonest-expiring pay-as-you-go credits lapse (ISO 8601), or null when you hold none. Each purchase expires 12 months after its own date and is never extended by a later one.

creditsLimitinteger required

Credits allotted by the plan for the current billing period. Excludes pay-as-you-go credits, so it is not a ceiling on creditsRemaining.

creditsUsedinteger required

Plan credits consumed so far in the current billing period, i.e. creditsLimit minus subscriptionCreditsRemaining. Pay-as-you-go credits spent are not counted here.

renewalDatestring date-time required

When the current billing period ends and the plan allowance is replaced (ISO 8601). Pay-as-you-go credits are untouched by this date; they keep their own 12-month expiry.

rpsLimitinteger required

Maximum sustained requests per second for this account.

cancelAtPeriodEndboolean required

Whether the subscription is set to end at the current period's end (no renewal).

Example response

{
  "plan": "custom",
  "active": true,
  "status": "active",
  "creditsRemaining": 684230,
  "subscriptionCreditsRemaining": 184230,
  "paygCreditsRemaining": 500000,
  "paygExpiresAt": "2027-03-02T00:00:00.000Z",
  "creditsLimit": 250000,
  "creditsUsed": 65770,
  "renewalDate": "2026-07-15T00:00:00.000Z",
  "rpsLimit": 20
}

Changes

No recorded changes to this operation across all 1 revision of this API.