--- title: "Get subscription and quota status" method: GET path: "/api/v1/subscription" --- # Get subscription and quota status `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` 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. ## Response `200` Current subscription and quota status - object - `plan` string, required: Plan identifier (e.g. "free", "custom"). - `active` boolean, 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. - `creditsRemaining` integer, 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. - `subscriptionCreditsRemaining` integer: 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. - `paygCreditsRemaining` integer: 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. - `paygExpiresAt` string, 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. - `creditsLimit` integer, 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. - `creditsUsed` integer, 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. - `renewalDate` string, 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. - `rpsLimit` integer, required: Maximum sustained requests per second for this account. - `cancelAtPeriodEnd` boolean, required: Whether the subscription is set to end at the current period's end (no renewal). ## Other responses - `401`: Unauthorized - the X-API-Key header is missing or invalid. - `429`: Too many requests - you exceeded this endpoint's own budget of 1 request per second per account (RATE_LIMITED). Your plan's per-second budget is untouched by these calls and is not what was exceeded: slow this polling loop, not your data requests. Honor the Retry-After header. - `500`: Internal server error - an unexpected error occurred in our API. Safe to retry; contact support if it persists. - `503`: Service unavailable - our API is temporarily unable to serve this request (capacity exhausted or overloaded). This is on our side, not yours and not an upstream service outage. Retry with backoff, honoring the Retry-After header. --- [API](https://skmtc.dev/fetchin/apis/fetchin-api.md) - [All operations](https://skmtc.dev/fetchin/apis/fetchin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fetchin/apis/fetchin-api/revisions/19a0b5d0320f?raw)