> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchin.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Subscription

> Check your current plan, remaining credits, RPS limit and billing status

## Endpoint

```
GET /api/v1/subscription
```

Read your account's current subscription state programmatically so you can confirm
access before routing traffic and detect a billing issue before it interrupts your
integration.

## Authentication

Include your API key in the request header:

```bash theme={null}
X-API-Key: your-api-key-here
```

## Parameters

None. The account is identified by your API key.

## Response

<ResponseField name="plan" type="string">
  Plan identifier, e.g. `"free"` or `"custom"`.
</ResponseField>

<ResponseField name="active" type="boolean">
  Whether the subscription is in good standing. `false` when the billing status is
  `past_due`, `incomplete`, `canceled` or `unpaid`. This flag is about billing only —
  check `creditsRemaining` separately to know whether you still have credits.
</ResponseField>

<ResponseField name="status" type="string">
  Raw billing status. Branch your integration on this value. `free` and `active` are
  good standing; `past_due` / `incomplete` / `unpaid` indicate a payment problem;
  `canceled` means the subscription has ended; `trialing` is a trial period.
</ResponseField>

<ResponseField name="creditsRemaining" type="number">
  Credits left in the current billing period.
</ResponseField>

<ResponseField name="creditsLimit" type="number">
  Total credits allotted for the current billing period.
</ResponseField>

<ResponseField name="creditsUsed" type="number">
  Credits consumed so far in the current billing period.
</ResponseField>

<ResponseField name="renewalDate" type="string">
  When the current period ends and credits renew (ISO 8601), e.g.
  `"2026-07-15T00:00:00.000Z"`.
</ResponseField>

<ResponseField name="rpsLimit" type="number">
  Maximum sustained requests per second for this account.
</ResponseField>

<ResponseField name="cancelAtPeriodEnd" type="boolean">
  Whether the subscription is set to end at the current period's end (i.e. it will not
  renew).
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.fetchin.io/api/v1/subscription" \
    -H "X-API-Key: your-api-key-here"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.fetchin.io/api/v1/subscription',
    {
      headers: {
        'X-API-Key': 'your-api-key-here'
      }
    }
  );

  const subscription = await response.json();
  console.log(subscription);
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'X-API-Key': 'your-api-key-here'
  }

  response = requests.get(
      'https://api.fetchin.io/api/v1/subscription',
      headers=headers
  )

  subscription = response.json()
  print(subscription)
  ```

  ```php PHP theme={null}
  <?php

  $apiKey = 'your-api-key-here';

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://api.fetchin.io/api/v1/subscription");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . $apiKey
  ]);

  $response = curl_exec($ch);
  $subscription = json_decode($response, true);

  curl_close($ch);
  print_r($subscription);
  ?>
  ```
</CodeGroup>

## Example Response

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "plan": "custom",
    "active": true,
    "status": "active",
    "creditsRemaining": 184230,
    "creditsLimit": 250000,
    "creditsUsed": 65770,
    "renewalDate": "2026-07-15T00:00:00.000Z",
    "rpsLimit": 20,
    "cancelAtPeriodEnd": false
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid API key",
    "code": "INVALID_API_KEY"
  }
  ```

  ```json 503 Service Unavailable theme={null}
  {
    "error": "Service temporarily unable to serve this request. Please retry.",
    "code": "SERVICE_UNAVAILABLE"
  }
  ```
</ResponseExample>

## Errors

See [Error Handling](/concepts/error-handling) for the full list of error codes and recommended handling.

* `401` `UNAUTHENTICATED` / `INVALID_API_KEY`
* `429` `RATE_LIMITED`
* `500` `INTERNAL_ERROR`
* `503` `SERVICE_UNAVAILABLE`

## Notes

<Info>
  This endpoint is **free** — it does not consume credits. It also returns `200` even
  when your quota is exhausted, so you can always use it to diagnose why calls are
  failing.
</Info>

<Tip>
  To decide whether you can call a data endpoint right now, check
  `active && creditsRemaining > 0`. Poll this endpoint periodically (not on every request)
  — the numbers reflect our billing store and may lag real-time usage by a few seconds.
</Tip>

## Use Cases

<CardGroup cols={2}>
  <Card title="Multi-provider arbitrage" icon="scale-balanced">
    Route traffic based on remaining credits and RPS across providers
  </Card>

  <Card title="Uninterrupted access" icon="shield-check">
    Detect a non-payment (`past_due`) or scheduled cancellation before it blocks you
  </Card>

  <Card title="Usage monitoring" icon="gauge">
    Track credit consumption and renewal timing programmatically
  </Card>

  <Card title="Capacity planning" icon="chart-line">
    Confirm your effective RPS limit before scaling up request volume
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /api/v1/subscription
openapi: 3.1.0
info:
  title: Fetchin API
  version: 1.0.0
  description: Public B2B data API for fetching posts and profile information
servers:
  - url: https://api.fetchin.io
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /api/v1/subscription:
    get:
      summary: Get subscription and quota status
      description: >-
        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). Values
        reflect our billing store and may lag real-time usage by a few seconds.
        Treat `active && creditsRemaining > 0` as "can I call the API right
        now?".
      parameters: []
      responses:
        '200':
          description: Current subscription and quota status
          content:
            application/json:
              schema:
                type: object
                required:
                  - plan
                  - active
                  - status
                  - creditsRemaining
                  - creditsLimit
                  - creditsUsed
                  - renewalDate
                  - rpsLimit
                  - cancelAtPeriodEnd
                properties:
                  plan:
                    type: string
                    description: Plan identifier (e.g. "free", "custom").
                    example: custom
                  active:
                    type: boolean
                    description: >-
                      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.
                    example: true
                  status:
                    type: string
                    description: >-
                      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.
                    enum:
                      - active
                      - free
                      - trialing
                      - past_due
                      - incomplete
                      - unpaid
                      - canceled
                    example: active
                  creditsRemaining:
                    type: integer
                    description: Credits left in the current billing period.
                    example: 184230
                  creditsLimit:
                    type: integer
                    description: Total credits allotted for the current billing period.
                    example: 250000
                  creditsUsed:
                    type: integer
                    description: Credits consumed so far in the current billing period.
                    example: 65770
                  renewalDate:
                    type: string
                    format: date-time
                    description: When the current period ends and credits renew (ISO 8601).
                    example: '2026-07-15T00:00:00.000Z'
                  rpsLimit:
                    type: integer
                    description: Maximum sustained requests per second for this account.
                    example: 20
                  cancelAtPeriodEnd:
                    type: boolean
                    description: >-
                      Whether the subscription is set to end at the current
                      period's end (no renewal).
                    example: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    Unauthorized:
      description: Unauthorized - the X-API-Key header is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingApiKey:
              value:
                error: Missing API key. Include X-API-Key header.
                code: UNAUTHENTICATED
            invalidApiKey:
              value:
                error: Invalid API key
                code: INVALID_API_KEY
    TooManyRequests:
      description: >-
        Too many requests - either your per-second rate limit (RATE_LIMITED) or
        your monthly credit quota (QUOTA_EXHAUSTED) was exceeded. Branch on
        `code` to tell them apart.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            rateLimited:
              value:
                error: Rate limit exceeded. Try again later.
                code: RATE_LIMITED
            quotaExhausted:
              value:
                error: Quota exceeded. Upgrade your plan or wait for renewal.
                code: QUOTA_EXHAUSTED
    InternalError:
      description: >-
        Internal server error - an unexpected error occurred in our API. Safe to
        retry; contact support if it persists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internalError:
              value:
                error: Internal server error
                code: INTERNAL_ERROR
    ServiceUnavailable:
      description: >-
        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.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            serviceUnavailable:
              value:
                error: >-
                  Service temporarily unable to serve this request. Please
                  retry.
                code: SERVICE_UNAVAILABLE
  schemas:
    Error:
      type: object
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: >-
            Human-readable description of what went wrong. For display/logging;
            do not branch on this string.
        code:
          type: string
          enum:
            - MISSING_PARAMETER
            - INVALID_PARAMETER
            - INVALID_URN
            - UNAUTHENTICATED
            - INVALID_API_KEY
            - FORBIDDEN
            - NOT_FOUND
            - PROFILE_NOT_FOUND
            - POST_NOT_FOUND
            - COMPANY_NOT_FOUND
            - RATE_LIMITED
            - QUOTA_EXHAUSTED
            - INTERNAL_ERROR
            - UPSTREAM_ERROR
            - SERVICE_UNAVAILABLE
            - UPSTREAM_TIMEOUT
          description: >-
            Stable, machine-readable error code. Branch your integration on this
            value, not on the HTTP status alone or the message text.
        details:
          type: object
          additionalProperties: true
          description: Optional structured context (e.g. creditsNeeded on quota errors).
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````