# Get usage

Get usage is a read in the HeadHoncho API. What the plan has used, what API calls cost and what this credential called, by day or by endpoint, with the credits left.

Page: https://headhoncho.app/docs/api/get_usage | Part of the HeadHoncho API docs: https://headhoncho.app/docs/api | Machine-readable: https://headhoncho.app/docs/api/openapi.json | Everything in one file: https://headhoncho.app/docs/api/llms-full.txt

## 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](https://headhoncho.app/docs/api/errors#credits).

Send your key as `Authorization: Bearer hh_live_...`. See [API keys](https://headhoncho.app/docs/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.

Paste your key on the web page and it fills a cURL line and a fetch line with your key and the example values. The page never sends the key anywhere. The same lines with a placeholder key are under Examples below.

## 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`](https://headhoncho.app/docs/api/errors#missing_key) | 401 | Send your key as Authorization: Bearer hh_live_... |
| [`unknown_key`](https://headhoncho.app/docs/api/errors#unknown_key) | 401 | That key is not one we issued, or it was revoked. |
| [`invalid`](https://headhoncho.app/docs/api/errors#invalid) | 422 | Some fields were refused. See fields. |
| [`no_credits`](https://headhoncho.app/docs/api/errors#no_credits) | 402 | Out of credits. Top up on Settings › Credits, or turn on auto top-up. |

## Related

- [Whoami](https://headhoncho.app/docs/api/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](https://headhoncho.app/docs/api/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](https://headhoncho.app/docs/api/get_company): One company this credential reaches: its name, time zone, country and service area.
- [Get credits](https://headhoncho.app/docs/api/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](https://headhoncho.app/docs/api/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](https://headhoncho.app/docs/companies).
- How the API fits together: [the model](https://headhoncho.app/docs/api/model), [API keys](https://headhoncho.app/docs/api/keys), [errors](https://headhoncho.app/docs/api/errors) and [the MCP server](https://headhoncho.app/docs/api/mcp).

## Examples

### Answer

```json
{
  "from": "2026-10-01",
  "to": "2026-10-26",
  "by": "day",
  "credits": {
    "left": 612.0,
    "per_call": 1.0
  },
  "plan": {
    "code": "core",
    "name": "Core",
    "status": "active"
  },
  "plan_usage": {
    "companies": 2,
    "subs": 3,
    "jobs_per_month": 128,
    "automation_devices": 1,
    "numbers": 2
  },
  "this_credential": {
    "name": "Reporting laptop",
    "calls_today": 14,
    "recent": [
      {
        "at": "2026-10-26T14:02:11Z",
        "endpoint": "list_jobs",
        "status": 200,
        "door": "rest",
        "credits": "1"
      }
    ]
  },
  "workspace_calls": {
    "calls": 412,
    "credits": 412.0,
    "rows": [
      {
        "day": "2026-10-25",
        "calls": 61,
        "credits": 61.0
      },
      {
        "day": "2026-10-26",
        "calls": 14,
        "credits": 14.0
      }
    ]
  }
}
```

### cURL

```bash
curl "https://api.headhoncho.app/api/v1/usage?from=2026-10-01&to=2026-10-26" \
  -H "Authorization: Bearer hh_live_..."
```

### Python

```python
import requests

response = requests.get(
    "https://api.headhoncho.app/api/v1/usage",
    headers={"Authorization": "Bearer hh_live_..."},
    params={
        "from": "2026-10-01",
        "to": "2026-10-26",
    },
)
response.raise_for_status()
print(response.json())
```

### JavaScript

```javascript
const response = await fetch("https://api.headhoncho.app/api/v1/usage?from=2026-10-01&to=2026-10-26", {
  headers: { Authorization: "Bearer hh_live_..." },
});
const data = await response.json();
console.log(data);
```

### Your AI

```text
Tool: get_usage
Arguments: from (date, optional), to (date, optional), by (text, optional)
Access: any key
Hints: readOnly=true, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, get usage with from 2026-10-01."
```