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

# GET /api/usage — check credit balance and plan limits

> Retrieve your plan name, compressions used, AI credit balances, and remaining capacity for the current billing period. No request body required.

This endpoint returns a snapshot of your account's current plan, compression usage, and AI credit balances. Use it to check whether you have remaining capacity before submitting a batch, or to surface usage data in your own tooling.

## Request

**Method:** `GET`\
**URL:** `https://fluximage.app/api/usage`\
**Authorization:** `Bearer flx_live_your_key_here`

No request body is required.

## Example request

```bash theme={null}
curl https://fluximage.app/api/usage \
  -H "Authorization: Bearer flx_live_your_key_here"
```

## Response

### 200 OK

```json theme={null}
{
  "plan": "pro",
  "compressor_used": 45,
  "compressor_limit": 99999,
  "ia_credits_used": 120,
  "ia_credits_monthly": 1000,
  "ia_topup_credits": 200,
  "ia_credits_remaining": 1080,
  "canCompress": true,
  "canUseIA": true,
  "topups": {
    "small": "...",
    "medium": "...",
    "large": "..."
  }
}
```

<Note>
  For Pro and Agency plans, `compressor_limit` returns a large number indicating effectively unlimited compressions. Use `canCompress` as the authoritative check for whether you can compress in the current period.
</Note>

#### Response fields

<ResponseField name="plan" type="string">
  Your current subscription plan. Possible values: `free`, `starter`, `pro`, `agency`.
</ResponseField>

<ResponseField name="compressor_used" type="number">
  Number of images you have compressed in the current billing period.
</ResponseField>

<ResponseField name="compressor_limit" type="number">
  Maximum images you can compress per billing period on your current plan.
</ResponseField>

<ResponseField name="ia_credits_used" type="number">
  Number of AI credits consumed from your monthly allocation in the current billing period.
</ResponseField>

<ResponseField name="ia_credits_monthly" type="number">
  Total AI credits included in your plan each month. `0` on the free plan.
</ResponseField>

<ResponseField name="ia_topup_credits" type="number">
  Additional AI credits you have purchased as top-ups. These are consumed after your monthly allocation is exhausted.
</ResponseField>

<ResponseField name="ia_credits_remaining" type="number">
  Total AI credits still available, combining remaining monthly credits and top-up credits: `(ia_credits_monthly − ia_credits_used) + ia_topup_credits`.
</ResponseField>

<ResponseField name="canCompress" type="boolean">
  `true` if you have remaining compression capacity for the current billing period.
</ResponseField>

<ResponseField name="canUseIA" type="boolean">
  `true` if you are on a paid plan and have at least one AI credit remaining.
</ResponseField>

<ResponseField name="topups" type="object">
  Contains keys `small`, `medium`, and `large` corresponding to the three AI credit top-up bundles available for purchase. You can use these values to initiate a checkout session for the desired pack size.
</ResponseField>

## Error codes

| Status | Error          | Description                        |
| ------ | -------------- | ---------------------------------- |
| `401`  | `Unauthorized` | The API key is missing or invalid. |