Usage and limits

Track image credits, historical usage, and current plan limits

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

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

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

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

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

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

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

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.

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

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.

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.