The request
Reference for Get statistics summary, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.
GET /api/v1/statistics/summary
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 and by_date (the date that puts a job in the range); companies it covers; jobs (total is every job in the range, leads is the jobs with a client name, a phone and an address, closed, canceled, canceled_by_phone, closing_rate in percent, callbacks); money (collected, parts, gross_profit, labour, net_profit, expenses, company_cut, lead_cost is the ad spend the range's jobs carry (each platform's spend divided by its jobs in the range, times the jobs), cost_per_lead is the Google Ads spend divided by the jobs whose source is Google Ads, profit_after_leads is net_profit less lead_cost, ad_spend is the range's spend as the ad platforms report it, spend_with_no_lead is the spend of a platform that brought no job, profit_after_advertising is net_profit less ad_spend); averages (ticket, close, return_per_lead). A figure with nothing behind it yet is null, never zero: cost_per_lead is null with no Google Ads account or no Google Ads job, and the three ad_spend figures are null with no ad account connected.
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. |
currency | text | The three-letter currency code (ISO 4217). Every money value in the answer is in it. |
companies | list of objects | The companies. |
companies[].id | id (text) | The id of this record. Ids are opaque text: keep them exactly as given. |
companies[].name | text | The name, as the app shows it. |
jobs | object | The jobs. |
jobs.total | whole number | The total, in the company's currency. |
jobs.leads | whole number | The leads. |
jobs.closed | whole number | True when the job is closed. |
jobs.canceled | whole number | The canceled. |
jobs.canceled_by_phone | whole number | The canceled by phone. |
jobs.closing_rate | number | The closing rate. |
jobs.callbacks | whole number | The callbacks. |
money | object | The money. |
money.collected | money (number) | The money received on the job so far. In the company's currency. |
money.parts | money (number) | The parts. In the company's currency. |
money.gross_profit | money (number) | The gross profit. In the company's currency. |
money.labour | number | The labour. |
money.net_profit | money (number) | The net profit. In the company's currency. |
money.expenses | money (number) | The expenses. In the company's currency. |
money.company_cut | number | The company cut. |
money.lead_cost | money (number) | The lead cost. In the company's currency. |
money.cost_per_lead | money (number) | The cost per lead. In the company's currency. |
money.profit_after_leads | money (number) | The profit after leads. In the company's currency. |
money.ad_spend | money (number) | The ad spend. In the company's currency. |
money.spend_with_no_lead | money (number) | The spend with no lead. In the company's currency. |
money.profit_after_advertising | money (number) | The profit after advertising. In the company's currency. |
averages | object | The averages. |
averages.ticket | number | The job number the ticket shows. |
averages.close | number | The close. |
averages.return_per_lead | number | The return per lead. |
The same numbers as the app
These are the tiles of the Statistics panel, from the same function, for the same range. Trashed jobs count in none of them.
Jobs and leads
jobs.total is the jobs created in the range, which is by_date=created, the default. jobs.leads is the part of them with a client name, a phone and an address. Choose scheduled or closed to count by another date; money follows the same jobs. ad_spend alone is the range's own spend, so it follows the dates and not the jobs.
Several companies
With no company_id the figures add up across every company the credential reaches, on the first company's clock.
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 areas: Every place the work happened, by postal code and city: jobs, closes, cancels, average ticket and profit, with a point to put on a map.
- 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.