The request
Reference for Get usage, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.
GET /api/v1/usage
Any key can call it. An answered call costs 1 credit; a refusal costs nothing. See credits.
Send your key as Authorization: Bearer hh_live_.... See API keys.
Parameters
| Name | Kind | Required | Description | Example |
|---|---|---|---|---|
from | date, in the query | No | First day of the API calls to count. Default: the first of this month. | 2026-10-01 |
to | date, in the query | No | Last day, inclusive. Default: today. | 2026-10-26 |
by | text, in the query | No | day (default) or endpoint: how to group the API calls. One of day, endpoint. | day |
Try it with your key
Paste your key and change the values. The box builds the call as a cURL line and a fetch line, ready to copy. It never sends anything itself.
Your key stays in this page and is never sent anywhere. Copy the line below and run it yourself.
What comes back
credits: what is left and what one call costs. plan: the plan in force, and plan_usage: what the workspace holds against it (companies, subs, jobs this month, devices, numbers). this_credential: calls_today, counted by UTC day, and its last calls, newest first, up to 50 from the past 7 days. workspace_calls: every API call the workspace paid for in the range, with calls and credits per day or per endpoint. Days are in the workspace's own time zone.
It never changes a record. It only reads the companies the key reaches.
Every field in the answer
Types are read from the example answer. Money is a plain number in the company's currency. A time carries its offset from UTC (Z is UTC). Ids are opaque text. A field with no line of its own here has its name spelled out; the common fields mean the same on every page.
| Field | Type | Meaning |
|---|---|---|
from | date (YYYY-MM-DD) | The first day of the range, inclusive. |
to | date (YYYY-MM-DD) | The last day of the range, inclusive. |
by | text | One of day, endpoint. |
credits | object | The credits. |
credits.left | number | Credits left in the workspace. |
credits.per_call | number | Credits one answered call costs. |
plan | object | The plan. |
plan.code | text | The code. |
plan.name | text | The name, as the app shows it. |
plan.status | text | The job status. |
plan_usage | object | The plan usage. |
plan_usage.companies | whole number | The companies. |
plan_usage.subs | whole number | The subs. |
plan_usage.jobs_per_month | whole number | The jobs per month. |
plan_usage.automation_devices | whole number | The automation devices. |
plan_usage.numbers | whole number | The numbers. |
this_credential | object | The this credential. |
this_credential.name | text | The name, as the app shows it. |
this_credential.calls_today | whole number | The calls today. |
this_credential.recent | list of objects | The recent. |
this_credential.recent[].at | time (ISO 8601, with offset) | The moment it happened. Carries its offset from UTC; Z is UTC. |
this_credential.recent[].endpoint | text | The endpoint. |
this_credential.recent[].status | whole number | The job status. |
this_credential.recent[].door | text | The door. |
this_credential.recent[].credits | text | The credits. |
workspace_calls | object | The workspace calls. |
workspace_calls.calls | whole number | How many calls. |
workspace_calls.credits | number | The credits. |
workspace_calls.rows | list of objects | The rows. |
workspace_calls.rows[].day | date (YYYY-MM-DD) | The day. |
workspace_calls.rows[].calls | whole number | How many calls. |
workspace_calls.rows[].credits | number | The credits. |
One credit a call
Every answered call costs the credits shown in per_call, this one included. A call that changes many jobs at once costs that for each job it changed. A refused call and a retried command cost nothing. There is no limit per minute or per month: the balance is the only brake.
Whose calls
this_credential is the calls made with the key or app asking. workspace_calls is every key and app of the workspace, as the credit ledger holds them. It names no job, customer or company.
Errors that apply
| Code | Status | What it means |
|---|---|---|
| `missing_key` | 401 | Send your key as Authorization: Bearer hh_live_... |
| `unknown_key` | 401 | That key is not one we issued, or it was revoked. |
| `invalid` | 422 | Some fields were refused. See fields. |
| `no_credits` | 402 | Out of credits. Top up on Settings › Credits, or turn on auto top-up. |
Related
- Whoami: Who this key or app acts as, which companies it reaches, what it may do, and the words to use in commands: statuses, job types and technicians.
- List companies: The companies this credential reaches, each with its name, time zone, country and service area. The same ids every other call takes as company_id.
- Get company: One company this credential reaches: its name, time zone, country and service area.
- Get credits: This month's credits: the plan's grant, what rolled over, what was bought, what was used and what is left.
- List plans: The plans on offer, with price and what each includes, and which one this workspace is on.
- The same records in the app: Multiple companies.
- How the API fits together: the model, API keys, errors and the MCP server.