# Usage and limits

Track image credits, historical usage, and current plan limits

## Automated usage alerts

We automatically send email notifications when your account reaches usage thresholds:

*   At 80% of your monthly limit
*   At 100% of your monthly limit

## Response headers

The simplest way to monitor usage is through the response headers returned with each image creation. These headers provide real-time usage information:

| Header | Description |
| --- | --- |
| `x-renders-allowed` | Total image credits available for the current billing period |
| `x-renders-consumed` | Number of image credits consumed by this request |
| `x-renders-used` | Total image credits used in the current billing period |

Monitoring tip

These headers make it easy to implement usage alerts in your application before hitting your plan limits.

## Operations

For historical image usage, use the endpoint below with [HTTP Basic authentication](/getting-started/using-the-api/api-keys/) and `usage:read`. See the [interactive API reference](https://htmlcsstoimage.com/api-docs) for its schema:

### Retrieve image usage history

`GET https://hcti.io/v1/usage`

Permission required: [`usage:read`](/getting-started/using-the-api/permissions/#permission-usage-read)

MCP tool: Not available

This endpoint returns comprehensive usage data broken down by:

*   Hourly usage (up to 72 recent entries)
*   Daily usage (up to 60 recent entries)
*   Monthly usage (up to 12 recent entries)
*   Per billing period statistics

### Example request

```bash
curl -X GET https://hcti.io/v1/usage \
  --user "$HCTI_API_ID:$HCTI_API_KEY"
```

### Response format

The response includes usage data organized into different time periods. This abbreviated example shows the shape:

```json
{
  "data": {
    "hour": { "2026-09-14T13:00:00Z": 29 },
    "day": { "2026-09-14T00:00:00Z": 838 },
    "month": { "2026-09-01T00:00:00Z": 5074 }
  },
  "per_billing_period": [
    {
      "total_images": 6240,
      "start": "2026-08-20T00:00:00Z",
      "end": "2026-09-20T00:00:00Z"
    }
  ]
}
```

Usage tracking

Consider implementing regular usage checks with this endpoint to monitor trends and plan capacity needs.

## Interpreting usage history

Hourly, daily, and monthly series are different views of the same image usage; do not add them together. Their timestamp keys identify the start of the interval. Intervals without recorded data may be omitted.

Calendar months are different from billing periods. `per_billing_period` follows your organization’s billing schedule and is ordered oldest first. A period still in progress contains usage recorded so far. Its `end` is a UTC timestamp when available and can be null; a future end means the period has not finished.

`GET /v1/usage` reports image history, not a count of Management API requests. It does not return the current allowance, overage setting, or maximum batch size. The Management API resource read/write rate-limit groups do not apply to this endpoint.

## Check current usage with MCP

With `usage:read` approved for your connection, call `check_usage` without arguments. It returns:

| Field | Description |
| --- | --- |
| `images_used` | Image credits used in the current billing period. |
| `images_allowed` | Image allowance reported for the current billing period. |
| `overages_enabled` | Whether the account allows overages. |
| `next_reset` | Date and time of the next reset. |

For example: **“Use HCTI to check my image usage, allowance, and next reset.”** When `images_allowed` is greater than zero, subtract `images_used` to calculate the remaining allowance. Do not infer a remaining allowance from a zero limit.

Call `get_max_batch_size` before preparing a batch. It also requires `usage:read` and takes no arguments. A result of `0` means batching is not supported; create images individually. Neither tool renders an image. See the [MCP tools reference](/integrations/mcp/tools/#usage-and-limits).

## Usage limits versus request limits

An exhausted image allowance can return `429` with a plan-limit message. Review your billing period and overage settings in the [dashboard](https://htmlcsstoimage.com/dashboard). For a larger image allowance or batch size, [compare plans](https://htmlcsstoimage.com/pricing). Waiting a minute does not restore image credits.

Management resource endpoints have separate per-minute request limits, shared with MCP. Those rejections identify a rate-limit group. See [rate limits and retry guidance](/getting-started/using-the-api/rate-limits/) to distinguish the two.

## Need help?

Talk to a human. Email [support@htmlcsstoimage.com](mailto:support@htmlcsstoimage.com) and we’ll help you get started.