> ## 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 Usage

> Your current balance and the credits you used over a date range, per endpoint and per day

## Endpoint

```
GET /api/v1/usage
```

Read your consumption programmatically: how many requests you made over a range of
days, how many of them were billable, how many credits they used, broken down per
endpoint and per day, together with the balance you have left right now. Use it to
reconcile an invoice, to feed your own billing or monitoring, or to forecast when you
will need more credits.

The same figures are in the dashboard, under **Usage report**, where they can be
downloaded as CSV.

## Authentication

Include your API key in the request header:

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

## Parameters

<ParamField query="from" type="string">
  First day of the range, `YYYY-MM-DD`, included. Days are **UTC** calendar days.
  Defaults to the first day of the current month.
</ParamField>

<ParamField query="to" type="string">
  Last day of the range, `YYYY-MM-DD`, included: the whole UTC day is counted.
  Defaults to today. A range covers at most **366 days**.
</ParamField>

## Response

<ResponseField name="from" type="string">
  First UTC day covered, `YYYY-MM-DD`.
</ResponseField>

<ResponseField name="to" type="string">
  Last UTC day covered, `YYYY-MM-DD`.
</ResponseField>

<ResponseField name="creditsRemaining" type="number">
  Your balance **now**, whatever the range: everything you can still spend, plan
  allowance plus [pay-as-you-go credits](/concepts/pay-as-you-go). Same figure as on
  [`GET /api/v1/subscription`](/api-reference/endpoint/get-subscription).
</ResponseField>

<ResponseField name="subscriptionCreditsRemaining" type="number">
  The plan half of `creditsRemaining`.
</ResponseField>

<ResponseField name="paygCreditsRemaining" type="number">
  The pay-as-you-go half of `creditsRemaining`.
</ResponseField>

<ResponseField name="requests" type="number">
  Every request made with your API keys over the range, whatever its outcome,
  refusals (`402`, `429`) and errors included.
</ResponseField>

<ResponseField name="billableRequests" type="number">
  The requests that cost credits: a delivered response, or a `404` for a record that
  does not exist. See [What is billed](/concepts/quotas#what-is-billed).
</ResponseField>

<ResponseField name="creditsUsed" type="number">
  Credits those billable requests used. Higher than `billableRequests` when you
  called endpoints that cost more than one credit.
</ResponseField>

<ResponseField name="endpoints" type="object[]">
  The same three figures per endpoint, busiest first, with the requests split by
  HTTP status.

  <Expandable title="properties">
    <ResponseField name="endpoint" type="string">
      The route called, e.g. `/api/v1/profile`.
    </ResponseField>

    <ResponseField name="requests" type="number">
      Requests to this endpoint.
    </ResponseField>

    <ResponseField name="billableRequests" type="number">
      Of which billable.
    </ResponseField>

    <ResponseField name="creditsUsed" type="number">
      Credits used on this endpoint.
    </ResponseField>

    <ResponseField name="statusCodes" type="object">
      Requests per HTTP status, e.g. `{ "200": 9120, "404": 610, "429": 3 }`. Sums to
      `requests`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="days" type="object[]">
  One entry per UTC day of the range, oldest first, days without traffic at `0`.
  Days that have not started yet are not listed, so a range ending in the future
  stops at today.

  <Expandable title="properties">
    <ResponseField name="date" type="string">
      The UTC day, `YYYY-MM-DD`.
    </ResponseField>

    <ResponseField name="requests" type="number">
      Requests that day.
    </ResponseField>

    <ResponseField name="billableRequests" type="number">
      Of which billable.
    </ResponseField>

    <ResponseField name="creditsUsed" type="number">
      Credits used that day.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.fetchin.io/api/v1/usage?from=2026-10-01&to=2026-10-31" \
    -H "X-API-Key: your-api-key-here"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ from: '2026-10-01', to: '2026-10-31' });
  const response = await fetch(
    `https://api.fetchin.io/api/v1/usage?${params}`,
    {
      headers: {
        'X-API-Key': 'your-api-key-here'
      }
    }
  );

  const usage = await response.json();
  console.log(usage.creditsUsed, usage.creditsRemaining);
  ```

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

  response = requests.get(
      'https://api.fetchin.io/api/v1/usage',
      headers={'X-API-Key': 'your-api-key-here'},
      params={'from': '2026-10-01', 'to': '2026-10-31'}
  )

  usage = response.json()
  print(usage['creditsUsed'], usage['creditsRemaining'])
  ```

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

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

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://api.fetchin.io/api/v1/usage?from=2026-10-01&to=2026-10-31");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . $apiKey
  ]);

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

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

## Example Response

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "from": "2026-10-01",
    "to": "2026-10-03",
    "creditsRemaining": 684230,
    "subscriptionCreditsRemaining": 184230,
    "paygCreditsRemaining": 500000,
    "requests": 30482,
    "billableRequests": 30214,
    "creditsUsed": 32154,
    "endpoints": [
      {
        "endpoint": "/api/v1/profile",
        "requests": 28377,
        "billableRequests": 28154,
        "creditsUsed": 28154,
        "statusCodes": { "200": 26401, "404": 1753, "429": 211, "503": 12 }
      },
      {
        "endpoint": "/api/v1/post/engagement",
        "requests": 2105,
        "billableRequests": 2060,
        "creditsUsed": 4000,
        "statusCodes": { "200": 1940, "404": 120, "429": 45 }
      }
    ],
    "days": [
      { "date": "2026-10-01", "requests": 9850, "billableRequests": 9771, "creditsUsed": 10411 },
      { "date": "2026-10-02", "requests": 10412, "billableRequests": 10305, "creditsUsed": 10978 },
      { "date": "2026-10-03", "requests": 10220, "billableRequests": 10138, "creditsUsed": 10765 }
    ]
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "from must be on or before to.",
    "code": "INVALID_PARAMETER"
  }
  ```

  ```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.

* `400` `INVALID_PARAMETER` — a date that is not `YYYY-MM-DD`, `from` after `to`, or more than 366 days
* `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, and it answers even when
  you are out of credits. Calls to it and to
  [`GET /api/v1/subscription`](/api-reference/endpoint/get-subscription) are left out
  of the figures it reports, so checking your consumption never adds to it.
</Info>

<Info>
  Like `/subscription`, it runs on its **own budget of 1 request per second per
  account**, separate from your plan's rate limit and from `/subscription`'s: it
  returns `X-RateLimit-Cost: 0` and never spends plan throughput. See
  [Rate Limits](/concepts/rate-limits#the-one-exception-account-endpoints).
</Info>

<Tip>
  Today's figures are live: a request shows up within about a minute. To follow a
  month as it goes, call this endpoint without parameters — it defaults to the
  current month to date. Consumption is recorded from 16 July 2026; earlier days
  report `0`.
</Tip>


## OpenAPI

````yaml GET /api/v1/usage
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/usage:
    get:
      summary: Get credit usage over a date range
      description: >-
        Return the authenticated account's current credit balance and its
        consumption over a range of UTC days: requests, billable requests and
        credits used, in total, per endpoint (split by HTTP status) and per day.
        Use it to reconcile an invoice or to feed your own billing and
        monitoring. Days are UTC calendar days, both ends included; `from`
        defaults to the first day of the current month and `to` to today, and a
        range covers at most 366 days. A request is billable when it cost
        credits: a delivered response, or a 404 for a record that does not
        exist; refusals (402, 429) and server errors never are. This endpoint is
        free - it does not consume credits - and answers even when your credits
        are exhausted. Calls to it and to `/api/v1/subscription` are left out of
        the figures it reports. Like `/api/v1/subscription`, it is metered on
        its OWN budget of 1 request per second per account, separate from your
        plan's per-second limit and from `/subscription`'s: it returns
        `X-RateLimit-Cost: 0` and carries no `X-RateLimit-Remaining` or
        `X-RateLimit-Reset`. Today's figures are live, within about a minute.
        Consumption is recorded from 2026-07-16; earlier days report 0.
      parameters:
        - name: from
          in: query
          required: false
          description: >-
            First UTC day of the range, `YYYY-MM-DD`, included. Defaults to the
            first day of the current month.
          schema:
            type: string
            format: date
            example: '2026-10-01'
        - name: to
          in: query
          required: false
          description: >-
            Last UTC day of the range, `YYYY-MM-DD`, included (the whole day is
            counted). Defaults to today. The range covers at most 366 days.
          schema:
            type: string
            format: date
            example: '2026-10-31'
      responses:
        '200':
          description: Current balance and consumption over the range
          content:
            application/json:
              schema:
                type: object
                required:
                  - from
                  - to
                  - creditsRemaining
                  - subscriptionCreditsRemaining
                  - paygCreditsRemaining
                  - requests
                  - billableRequests
                  - creditsUsed
                  - endpoints
                  - days
                properties:
                  from:
                    type: string
                    format: date
                    description: First UTC day covered.
                    example: '2026-10-01'
                  to:
                    type: string
                    format: date
                    description: Last UTC day covered.
                    example: '2026-10-03'
                  creditsRemaining:
                    type: integer
                    description: >-
                      Your balance now, whatever the range: plan allowance plus
                      pay-as-you-go credits. Same figure as on
                      /api/v1/subscription.
                    example: 684230
                  subscriptionCreditsRemaining:
                    type: integer
                    description: The plan half of creditsRemaining.
                    example: 184230
                  paygCreditsRemaining:
                    type: integer
                    description: The pay-as-you-go half of creditsRemaining.
                    example: 500000
                  requests:
                    type: integer
                    description: >-
                      Every request made with your API keys over the range,
                      whatever its outcome: refusals (402, 429) and errors
                      included. Calls to /subscription and /usage are not
                      counted.
                    example: 30482
                  billableRequests:
                    type: integer
                    description: >-
                      The requests that cost credits: a delivered response, or a
                      404 for a record that does not exist.
                    example: 30214
                  creditsUsed:
                    type: integer
                    description: >-
                      Credits used by the billable requests. Higher than
                      billableRequests when endpoints costing more than one
                      credit were called.
                    example: 32154
                  endpoints:
                    type: array
                    description: The same figures per endpoint, busiest first.
                    items:
                      type: object
                      required:
                        - endpoint
                        - requests
                        - billableRequests
                        - creditsUsed
                        - statusCodes
                      properties:
                        endpoint:
                          type: string
                          description: The route called.
                          example: /api/v1/profile
                        requests:
                          type: integer
                          example: 28377
                        billableRequests:
                          type: integer
                          example: 28154
                        creditsUsed:
                          type: integer
                          example: 28154
                        statusCodes:
                          type: object
                          description: Requests per HTTP status. Sums to requests.
                          additionalProperties:
                            type: integer
                          example:
                            '200': 26401
                            '404': 1753
                            '429': 211
                            '503': 12
                  days:
                    type: array
                    description: >-
                      One entry per UTC day of the range up to today, oldest
                      first, idle days at 0. Days that have not started are not
                      listed.
                    items:
                      type: object
                      required:
                        - date
                        - requests
                        - billableRequests
                        - creditsUsed
                      properties:
                        date:
                          type: string
                          format: date
                          example: '2026-10-01'
                        requests:
                          type: integer
                          example: 9850
                        billableRequests:
                          type: integer
                          example: 9771
                        creditsUsed:
                          type: integer
                          example: 10411
        '400':
          description: >-
            Invalid range (INVALID_PARAMETER): a date that is not YYYY-MM-DD,
            from after to, or more than 366 days.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                reversedRange:
                  value:
                    error: from must be on or before to.
                    code: INVALID_PARAMETER
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          description: >-
            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.
          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: >-
                      This endpoint allows 1 request(s) per second per account,
                      counted separately from your plan's 10 RPS — which this
                      call does not consume.
                    code: RATE_LIMITED
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  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
            - ENDPOINT_REMOVED
            - 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. On QUOTA_EXHAUSTED it carries the
            balance breakdown at the moment of the rejection - creditsRemaining,
            subscriptionCreditsRemaining, paygCreditsRemaining - plus
            buyCreditsUrl, the self-serve page for buying more credits. Always
            additive and never guaranteed: read it for diagnostics and logs, but
            branch on `code` and do not require any field of it.
  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
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.