Monitoring API Usage

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.

Usage API Endpoint

For historical image usage, use the endpoint below with HTTP Basic authentication and usage:read. See the interactive API reference for its schema:

Retrieve image usage history

GET /v1/usage

Permission required: 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

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:

{
  "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.

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. For a larger image allowance or batch size, compare plans. 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 to distinguish the two.

Need help?

Talk to a human. Please email us support@htmlcsstoimage.com with any questions and we’ll gladly help you get started.