---
layout: page
title: Usage and limits
permalink: /management-api/usage/
parent: Management API
nav_order: 2
description: >-
  Learn how to monitor your HTML/CSS to Image API usage through response headers and dedicated endpoints.
---

# Monitoring API Usage
{: .no_toc }
{: .fs-9 }

Track image credits, historical usage, and current plan limits
{: .fs-6 .fw-300 }

<hr>

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

{% include hint.md title="Monitoring Tip" text="These headers make it easy to implement usage alerts in your application before hitting your plan limits." %}

## Usage API Endpoint

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:

{% include operation-cards.html resource="usage" %}

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"
    }
  ]
}
```

{% include hint.md title="Usage Tracking" text="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.

{% include code_footer.md version=1 %}