List ad accounts

The request

Reference for List ad accounts, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.

GET /api/v1/ad-accounts

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`

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 API key company_id (optional, id)

Your key stays in this page and is never sent anywhere. Copy the line below and run it yourself.

What comes back

items, one connected ad account each: id, company, provider, account_id, account_name, account_timezone, currency, status, status_detail, live, connected_by, connected_at, last_synced_at, last_spend_rows. call_tracking, the CallRail connections: id, company, provider, account_id, account_name, status, status_detail, live, last_synced_at, key_hint. No key or token is ever shown.

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
`items`	list of objects	The rows on this page.
`items[].id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`items[].company`	object	The company.
`items[].company.id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`items[].company.name`	text	The name, as the app shows it.
`items[].provider`	text	The provider.
`items[].account_id`	id (text)	The id of the account.
`items[].account_name`	text	The account name.
`items[].account_timezone`	text	The account timezone.
`items[].currency`	text	The three-letter currency code (ISO 4217). Every money value in the answer is in it.
`items[].status`	text	The job status.
`items[].status_detail`	text	The status detail.
`items[].live`	true or false	The live.
`items[].connected_by`	text	The connected by.
`items[].connected_at`	time (ISO 8601, with offset)	When it was connected. Carries its offset from UTC; `Z` is UTC.
`items[].last_synced_at`	time (ISO 8601, with offset)	When it was last synced. Carries its offset from UTC; `Z` is UTC.
`items[].last_spend_rows`	whole number	The last spend rows.
`call_tracking`	list of objects	The call tracking.
`call_tracking[].id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`call_tracking[].company`	object	The company.
`call_tracking[].company.id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`call_tracking[].company.name`	text	The name, as the app shows it.
`call_tracking[].provider`	text	The provider.
`call_tracking[].account_id`	id (text)	The id of the account.
`call_tracking[].account_name`	text	The account name.
`call_tracking[].status`	text	The job status.
`call_tracking[].status_detail`	text	The status detail.
`call_tracking[].live`	true or false	The live.
`call_tracking[].last_synced_at`	time (ISO 8601, with offset)	When it was last synced. Carries its offset from UTC; `Z` is UTC.
`call_tracking[].key_hint`	text	The key hint.

Connecting an account

Signing in to Google, Meta or Microsoft and choosing the ad account both happen in the app. Once connected, the account shows here.

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.

List campaigns: Spend by campaign for a range, with the calls, leads, lead cost, revenue and profit each one produced, and the revenue that could not be placed.
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.

Answer cURL Python JavaScript Your AI

{
  "items": [
    {
      "id": "adc_5e10",
      "company": {
        "id": "cmp_14f5",
        "name": "Sunrise Moving"
      },
      "provider": "google_ads",
      "account_id": "123-456-7890",
      "account_name": "Sunrise Moving Ads",
      "account_timezone": "America/Chicago",
      "currency": "USD",
      "status": "connected",
      "status_detail": "",
      "live": true,
      "connected_by": "Ariel T.",
      "connected_at": "2026-09-02T14:10:00Z",
      "last_synced_at": "2026-10-26T13:00:04Z",
      "last_spend_rows": 31
    }
  ],
  "call_tracking": [
    {
      "id": "cn_2b90",
      "company": {
        "id": "cmp_14f5",
        "name": "Sunrise Moving"
      },
      "provider": "callrail",
      "account_id": "ACC1f3",
      "account_name": "Sunrise Moving",
      "status": "connected",
      "status_detail": "",
      "live": true,
      "last_synced_at": "2026-10-26T13:00:04Z",
      "key_hint": "...91af"
    }
  ]
}

curl "https://api.headhoncho.app/api/v1/ad-accounts?company_id=cmp_14f5" \
  -H "Authorization: Bearer hh_live_..."

import requests

response = requests.get(
    "https://api.headhoncho.app/api/v1/ad-accounts",
    headers={"Authorization": "Bearer hh_live_..."},
    params={
        "company_id": "cmp_14f5",
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.headhoncho.app/api/v1/ad-accounts?company_id=cmp_14f5", {
  headers: { Authorization: "Bearer hh_live_..." },
});
const data = await response.json();
console.log(data);

Tool: list_ad_accounts
Arguments: company_id (id, optional)
Access: read on Statistics and marketing
Hints: readOnly=true, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, list ad accounts with company_id cmp_14f5."