The request
Reference for List campaigns, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.
GET /api/v1/campaigns
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: the first company the credential reaches. | cmp_14f5 |
from | date, in the query | No | First day. Default: the last 30 days. | 2026-09-27 |
to | date, in the query | No | Last day, included. Default: today. | 2026-10-26 |
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, company_id; rows, one per campaign: campaign_id, campaign, channel, tracking (tracked, partly_tracked or untracked) and tracking_label, spend, leads, cost_per_lead, jobs, cost_per_job, revenue, subcontractors, parts, fees, profit, roas. leads is every job placed on the campaign it came from; cost_per_lead is the campaign's spend divided by those jobs, never the platform's click price. jobs and cost_per_job are kept for older integrations: jobs is the same count and cost_per_job the same figure. totals for the table. unattributed_revenue: money no campaign could be named for. A ratio with nothing to divide by is null.
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. |
company_id | id (text) | The id of the company. |
currency | text | The three-letter currency code (ISO 4217). Every money value in the answer is in it. |
rows | list of objects | The rows. |
rows[].campaign_id | id (text) | The ad platform's id for the campaign. |
rows[].campaign | text | The ad campaign's name. |
rows[].channel | text | The channel. |
rows[].tracking | text | The tracking. |
rows[].tracking_label | text | The tracking label. |
rows[].spend | money (number) | What was spent. In the company's currency. |
rows[].leads | whole number | The leads. |
rows[].cost_per_lead | money (number) | The cost per lead. In the company's currency. |
rows[].jobs | whole number | The jobs. |
rows[].cost_per_job | money (number) | The cost per job. In the company's currency. |
rows[].revenue | number | The revenue. |
rows[].subcontractors | number | The subcontractors. |
rows[].parts | money (number) | The parts. In the company's currency. |
rows[].fees | money (number) | What the payment processor kept. In the company's currency. |
rows[].profit | money (number) | The job's profit, worked out the way the app works it out. In the company's currency. |
rows[].roas | number | The roas. |
totals | object | The totals. |
totals.spend | money (number) | What was spent. In the company's currency. |
totals.leads | whole number | The leads. |
totals.cost_per_lead | money (number) | The cost per lead. In the company's currency. |
totals.jobs | whole number | The jobs. |
totals.cost_per_job | money (number) | The cost per job. In the company's currency. |
totals.revenue | number | The revenue. |
totals.profit | money (number) | The job's profit, worked out the way the app works it out. In the company's currency. |
totals.roas | number | The roas. |
unattributed_revenue | number | The unattributed revenue. |
The same numbers as the app
These are the rows of the Marketing campaign table. A click ID names a network, never a campaign, so a job is placed on a campaign by the name the call tracker recorded. Money that cannot be placed is shown, never dropped.
One company
A campaign table is one company's. Ask for another with company_id.
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
- List ad accounts: The ad accounts and call tracking each company has connected, and how each one is doing.
- List agency jobs: The agency's jobs feed on a key: one row per job that opened or closed in the range, in the agency's sixteen columns, a page at a time.
- Get agency feed: How the workspace sends closed jobs to its agency: the webhook address, the daily file, whether it is on, and the last tries.
- The same records in the app: the Statistics panel.
- How the API fits together: the model, API keys, errors and the MCP server.