The request
Reference for Get statistics areas, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.
GET /api/v1/statistics/areas
The key needs the Statistics and marketing area at read. 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 |
|---|---|---|---|---|
company_id | id, in the query | No | One company. Default: every company the credential reaches. | cmp_14f5 |
from | date, in the query | No | First day. Default: the last 30 days, as the Statistics panel does. | 2026-10-01 |
to | date, in the query | No | Last day, included. Default: today in the company's time zone. | 2026-10-26 |
by_date | text, in the query | No | Which date puts a job in the range: created (default), scheduled or closed. One of created, scheduled, closed. | created |
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
from, to, by_date, then areas, one per place: key, label, city, state, postal_code, jobs, closed, canceled, decided, closing_rate (a share from 0 to 1, null with nothing decided), average_ticket, net, net_per_job, lat and lng (the middle of its jobs), pinned and last_job. workspace: net_per_job and closing_rate for the whole range, to compare a place against.
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_date | text | One of created, scheduled, closed. |
areas | list of objects | The areas. |
areas[].key | text | A short code for this item. Match on it in code. |
areas[].label | text | The name the app shows for it. |
areas[].city | text | The city. |
areas[].state | text | The state or region. |
areas[].postal_code | text | The postal code. |
areas[].jobs | whole number | The jobs. |
areas[].closed | whole number | True when the job is closed. |
areas[].canceled | whole number | The canceled. |
areas[].decided | whole number | The decided. |
areas[].closing_rate | number | The closing rate. |
areas[].average_ticket | number | The average ticket. |
areas[].net | money (number) | The net amount, after what is owed either way. In the company's currency. |
areas[].net_per_job | money (number) | The net per job. In the company's currency. |
areas[].lat | number | The lat. |
areas[].lng | number | The lng. |
areas[].pinned | whole number | The pinned. |
areas[].last_job | date (YYYY-MM-DD) | The last job. |
workspace | object | The workspace. |
workspace.net_per_job | money (number) | The net per job. In the company's currency. |
workspace.closing_rate | number | The closing rate. |
Places, not people
Each row is a postal code and city, never a street. The point is the average of the jobs in it. The app's above and below average labels are not given: read the figures.
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. |
| `no_access` | 403 | This credential does not reach that. Ask the person who made it for access. |
| `not_found` | 404 | No such record in the companies this credential reaches. |
| `out_of_scope` | 404 | No such company in the companies this credential reaches. |
| `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
- Get statistics summary: Jobs and leads for a range and the money they left: profit, lead cost, cost per lead, profit after leads, ad spend and profit after advertising.
- List area jobs: The jobs behind one area on the map, newest first, twenty-five a page, with status, price, profit and where they came from.
- List job pins: Each job in the range that has a point on the map, newest first, up to 400, with its status, price and profit. Narrow it with a box.
- The same records in the app: the Statistics panel.
- How the API fits together: the model, API keys, errors and the MCP server.