Reference
Account usage
GET /v1/account — current-month usage for your API key's website, and (Free plan) how close you are to the monthly cap.
Returns the current UTC-month usage for the website your API key belongs to, plus — on the Free plan — how close your account is to the monthly image cap.
Request
GET /v1/account
Terminal
curl https://api.helloimg.io/v1/account \
-H "Authorization: Bearer <your API key>"
Response
Free plan
{
"plan": "free",
"month": "2026-08",
"website": {
"domain": "example.com",
"images": 12,
"bytes_saved": 3456789
},
"limit": {
"monthly_images": 1000,
"used": 34,
"remaining": 966,
"over_limit": false,
"resets_at": "2026-09-01T00:00:00Z"
}
}
Unlimited, Unlimited + AI, and Reseller + AI
Same shape, but limit is always null — none of these plans have an
image cap. plan is "unlimited", "unlimited_ai", or "reseller_ai"
respectively:
{
"plan": "unlimited",
"month": "2026-08",
"website": {
"domain": "example.com",
"images": 41230,
"bytes_saved": 8912345671
},
"limit": null
}
Older API keys
A legacy key — one issued before self-service, per-website key management existed — returns a simpler shape: no website or limit details, just the key's own usage.
{
"plan": "legacy",
"month": "2026-08",
"website": null,
"usage": {
"images": 512,
"bytes_saved": 91234567
},
"limit": null
}
Fields
| Field | Type | Description |
|---|---|---|
plan | string | free, unlimited, unlimited_ai, reseller_ai, or legacy — see Plans & limits. |
month | string | The UTC calendar month these numbers cover, as YYYY-MM. |
website | object | null | The website your API key belongs to. null for a legacy key — no website is on file for it. |
website.domain | string | The website's domain. |
website.images | number | Images processed this month, summed across every active key on this website (a website can have up to 2). |
website.bytes_saved | number | Total bytes saved this month for this website. |
usage | object | Legacy keys only — the same images / bytes_saved shape as website, for the key itself. |
limit | object | null | null on every plan except Free — no other plan has an image cap. |
limit.monthly_images | number | The Free plan's monthly image cap (1,000). |
limit.used | number | Images processed this month, across your whole account — every website, not just this one. See the callout below. |
limit.remaining | number | monthly_images - used, floored at 0. |
limit.over_limit | boolean | true once used reaches monthly_images. |
limit.resets_at | string | ISO 8601 timestamp for the start of next UTC month, when used resets to 0. |
limit.used is your account's total, not just this website's — the Free
plan's 1,000-image cap is shared across every website on the account, while
website.images reports only this one site. A Free-plan account with two
websites could see website.images: 12 here and limit.used: 340 if the
other website processed the rest.Caching
The response is cached for up to 60 seconds per API key — a burst of calls right after processing a batch of images may not reflect the very latest count immediately.
Errors
| Status | Body | Cause |
|---|---|---|
401 | { "error": "invalid api key" } | Missing or malformed Authorization header. Applies to every /v1/* route — one shared check in front of all of them. |
503 | { "error": "usage unavailable" } | Usage data is temporarily unavailable. Retry shortly. |