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

# Usage & Limits

> Returns your plan, limits and quota usage for the current billing period. This call is free: it doesn't count against your quota, isn't logged, and keeps working when your quota is used up or your subscription has expired. It has its own limit of 60 calls per minute per key.

Get your plan, limits and how much of your quota you've used.

```text theme={null}
https://fapihub.com/v2/account/usage/
```

* **Free:** calls don't count against your quota and aren't logged.
* **Always available:** keeps working when your quota is used up or your subscription has expired.
* **Own limit:** 60 calls per minute per API key.
* **Auth:** the same `ApiKey` header as every other endpoint.

> [!TIP]
>
> Call this endpoint before a large batch to check that `usage.remaining` covers the number of images you plan to process.

### Response fields

| Field | Meaning |
| - | - |
| `plan.id` | `basic`, `pro`, `ultra`, `mega`, `per_usage` or `custom` |
| `plan.billing` | `monthly`, or `lifetime` for per-usage plans, which never reset. For lifetime plans `billing_period` is `null`. |
| `status` | `active`, `trial`, `over_limit`, `past_due`, `cancelled`, `expired` or `incomplete` |
| `can_make_requests` | Whether image requests are currently accepted |
| `limits.requests` | Quota per billing period, or the lifetime total |
| `limits.requests_per_minute` | Per-minute rate limit |
| `usage.used` / `usage.remaining` / `usage.percent_used` | Quota consumed and left |
| `usage.successful` / `usage.failed` | Breakdown of `used`; `failed` = counted 4xx errors |
| `billing_period.start` / `.end` | Dates; the quota resets on `end` |
| `cancel_at_period_end` | Whether the subscription is set to cancel at the end of the period |
| `end_date` | Subscription end date or `null` |

See [Rate Limit](https://docs.fapihub.com/rate-limit.md) for the limits of each plan and what counts against your quota.

```bash cURL theme={null}
curl "https://fapihub.com/v2/account/usage/" \
  -H "ApiKey: your_api_key"
```

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

response = requests.get(
    "https://fapihub.com/v2/account/usage/",
    headers={"ApiKey": "your_api_key"},
)

data = response.json()["data"]
print(f"{data['usage']['remaining']} of {data['limits']['requests']} requests left")
```

```javascript JavaScript theme={null}
const response = await fetch("https://fapihub.com/v2/account/usage/", {
  headers: { "ApiKey": "your_api_key" },
});

const { data } = await response.json();
console.log(`${data.usage.remaining} of ${data.limits.requests} requests left`);
```

```php PHP theme={null}
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://fapihub.com/v2/account/usage/",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["ApiKey: your_api_key"]
]);

$response = json_decode(curl_exec($curl), true);
curl_close($curl);

$data = $response["data"];
echo $data["usage"]["remaining"] . " of " . $data["limits"]["requests"] . " requests left";
?>
```

```json 200 theme={null}
{
  "success": true,
  "data": {
    "plan": { "id": "pro", "name": "Pro", "billing": "monthly", "price": 15.0 },
    "status": "active",
    "can_make_requests": true,
    "limits": { "requests": 7500, "requests_per_minute": 150 },
    "usage": { "used": 1240, "remaining": 6260, "percent_used": 16.5, "successful": 1225, "failed": 15 },
    "billing_period": { "start": "2026-10-01", "end": "2026-11-01" },
    "cancel_at_period_end": false,
    "end_date": null
  },
  "timestamp": "2026-10-27T10:00:00+00:00"
}
```

```json 401 theme={null}
{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or inactive"
  },
  "timestamp": "2026-10-27T10:00:00+00:00"
}
```


## OpenAPI

````yaml GET /account/usage/
openapi: 3.1.0
info:
  title: FAPIHub API
  description: >-
    AI image processing API: background removal, subject masks, background blur,
    solid color and gradient backgrounds, and drop shadows. Images are uploaded
    as `multipart/form-data` in a field named `image`. Every path ends with a
    trailing slash, and the trailing slash is required.
  version: 2.0.0
  contact:
    email: support@fapihub.com
    url: https://fapihub.com
servers:
  - url: https://fapihub.com/v2
security:
  - ApiKeyAuth: []
tags:
  - name: Image processing
    description: Endpoints that take an image and return a processed PNG.
  - name: Account
    description: Plan, limits and usage.
paths:
  /account/usage/:
    get:
      tags:
        - Account
      summary: Usage & Limits
      description: >-
        Returns your plan, limits and quota usage for the current billing
        period. This call is free: it doesn't count against your quota, isn't
        logged, and keeps working when your quota is used up or your
        subscription has expired. It has its own limit of 60 calls per minute
        per key.
      operationId: getUsage
      responses:
        '200':
          description: Your plan, limits and usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
              example:
                success: true
                data:
                  plan:
                    id: pro
                    name: Pro
                    billing: monthly
                    price: 15
                  status: active
                  can_make_requests: true
                  limits:
                    requests: 7500
                    requests_per_minute: 150
                  usage:
                    used: 1240
                    remaining: 6260
                    percent_used: 16.5
                    successful: 1225
                    failed: 15
                  billing_period:
                    start: '2026-10-01'
                    end: '2026-11-01'
                  cancel_at_period_end: false
                  end_date: null
                timestamp: '2026-10-27T10:00:00+00:00'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  schemas:
    UsageResponse:
      type: object
      required:
        - success
        - data
        - timestamp
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          properties:
            plan:
              type: object
              properties:
                id:
                  type: string
                  enum:
                    - basic
                    - pro
                    - ultra
                    - mega
                    - per_usage
                    - custom
                  description: Plan identifier.
                name:
                  type: string
                  description: Plan display name.
                billing:
                  type: string
                  enum:
                    - monthly
                    - lifetime
                  description: >-
                    `monthly`, or `lifetime` for per-usage plans, which never
                    reset.
                price:
                  type: number
                  description: Plan price.
            status:
              type: string
              enum:
                - active
                - trial
                - over_limit
                - past_due
                - cancelled
                - expired
                - incomplete
              description: Subscription status.
            can_make_requests:
              type: boolean
              description: Whether image requests are currently accepted.
            limits:
              type: object
              properties:
                requests:
                  type: integer
                  description: Quota per billing period, or the lifetime total.
                requests_per_minute:
                  type: integer
                  description: Per-minute rate limit.
            usage:
              type: object
              properties:
                used:
                  type: integer
                  description: Requests counted against your quota.
                remaining:
                  type: integer
                  description: Requests left in your quota.
                percent_used:
                  type: number
                  description: Share of the quota used, in percent.
                successful:
                  type: integer
                  description: Successful requests included in `used`.
                failed:
                  type: integer
                  description: Counted 4xx errors included in `used`.
            billing_period:
              type:
                - object
                - 'null'
              description: Current billing period. `null` for lifetime plans.
              properties:
                start:
                  type: string
                  format: date
                  description: Start of the billing period.
                end:
                  type: string
                  format: date
                  description: End of the billing period. The quota resets on this date.
            cancel_at_period_end:
              type: boolean
              description: >-
                Whether the subscription is set to cancel at the end of the
                period.
            end_date:
              type:
                - string
                - 'null'
              description: Subscription end date, or `null`.
        timestamp:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - success
        - error
        - timestamp
      properties:
        success:
          type: boolean
          const: false
          description: Always `false` for errors.
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - missing_image
                - invalid_image
                - invalid_parameter
                - api_key_required
                - invalid_api_key
                - insufficient_credits
                - subscription_expired
                - subscription_inactive
                - no_subscription
                - rate_limit_exceeded
                - internal_error
                - timeout
                - external_api_error
              description: >-
                Machine-readable error code. See the Errors page for what each
                code means.
            message:
              type: string
              description: Human-readable description of the error.
            request_id:
              type: string
              description: >-
                Included whenever the request was logged. Send it to
                support@fapihub.com when you report a problem.
        timestamp:
          type: string
          format: date-time
          description: Time of the response.
    RateLimitError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            limit:
              type: integer
              description: Your per-minute request limit.
            retry_after:
              type: integer
              description: Seconds to wait before retrying.
            reset_at:
              type: string
              format: date-time
              description: When the per-minute window resets.
  responses:
    Unauthorized:
      description: >-
        The `ApiKey` header is missing, or the key is wrong or deactivated.
        Doesn't count against your quota.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            api_key_required:
              summary: Missing ApiKey header
              value:
                success: false
                error:
                  code: api_key_required
                  message: Please provide an API key in the ApiKey header
                  request_id: req_12345
                timestamp: '2026-10-27T10:00:00+00:00'
            invalid_api_key:
              summary: Wrong or deactivated key
              value:
                success: false
                error:
                  code: invalid_api_key
                  message: The provided API key is invalid or inactive
                  request_id: req_12345
                timestamp: '2026-10-27T10:00:00+00:00'
    RateLimitExceeded:
      description: >-
        Per-minute rate limit exceeded. Wait `Retry-After` seconds, then retry.
        Doesn't count against your quota.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          examples:
            rate_limit_exceeded:
              summary: Rate limit exceeded
              value:
                success: false
                error:
                  code: rate_limit_exceeded
                  message: Rate limit of 10 requests per minute exceeded
                  request_id: req_12346
                timestamp: '2026-10-27T10:00:00+00:00'
                limit: 10
                retry_after: 42
                reset_at: '2026-10-27T10:01:00+00:00'
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
          example: 42
        X-RateLimit-Limit:
          description: Your per-minute request limit.
          schema:
            type: integer
          example: 10
        X-RateLimit-Remaining:
          description: Requests left in the current minute (always `0` on a 429).
          schema:
            type: integer
          example: 0
        X-RateLimit-Reset:
          description: When the per-minute window resets, as a Unix timestamp.
          schema:
            type: integer
          example: 1793095260
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: ApiKey
      description: >-
        Your API key (looks like `bg_live_sk_…`). Create one in the dashboard at
        https://fapihub.com/dashboard/.

````

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