List tables

The request

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

GET /api/v1/data/tables

The key or app needs the Raw data area at read. It counts as a read call: 300 a minute for each key or connected app. See rate limits.

Send your key as Authorization: Bearer hh_live_.... See API keys.

Parameters

Name	Kind	Required	Description	Example
`company_id`	id, in the query	No	Default: the first company the credential reaches.	`cmp_14f5`

What comes back

schemas, one per provider (google_ads, meta_ads, microsoft_ads, callrail, headhoncho), each with its tables: key, name, grain, caveat, columns (key, label, kind), the date column if any, and available.

It never changes a record. It only reads the companies the key reaches.

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.
`expired_token`	401	That token has expired. Refresh it, or connect the app again.
`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.
`rate_limited`	429	Too many calls this minute. Wait and try again.
`not_connected`	409	This company has not connected that provider yet.

Read table: Rows of one raw table for one company and a date range, exactly as the provider reported them. No joins, no derived figures.
Export table: One raw table as a CSV file for a company and a date range, up to 50,000 rows, with its caveat in the last lines.
The same records in the app: the Raw data board.
How the API fits together: the model, API keys, errors and the MCP server.

Answer cURL Python JavaScript Your AI

{
  "schemas": [
    {
      "key": "google_ads",
      "label": "Google Ads",
      "available": true,
      "tables": [
        {
          "key": "google_ads.spend_by_day",
          "name": "spend_by_day",
          "grain": "One row per campaign per day.",
          "date_column": "date",
          "columns": [
            {
              "key": "date",
              "label": "Date",
              "kind": "date"
            },
            {
              "key": "campaign_name",
              "label": "Campaign",
              "kind": "text"
            },
            {
              "key": "cost",
              "label": "Spend",
              "kind": "money"
            },
            {
              "key": "clicks",
              "label": "Clicks",
              "kind": "number"
            }
          ]
        }
      ]
    },
    {
      "key": "callrail",
      "label": "CallRail",
      "available": true,
      "tables": [
        {
          "key": "callrail.calls",
          "name": "calls",
          "grain": "One row per tracked call.",
          "date_column": "started_at",
          "columns": [
            {
              "key": "started_at",
              "label": "Started",
              "kind": "datetime"
            },
            {
              "key": "customer_phone",
              "label": "Caller",
              "kind": "text"
            },
            {
              "key": "has_identifier",
              "label": "Click id",
              "kind": "boolean"
            }
          ]
        }
      ]
    }
  ]
}

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

import requests

response = requests.get(
    "https://api.headhoncho.app/api/v1/data/tables",
    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/data/tables?company_id=cmp_14f5", {
  headers: { Authorization: "Bearer hh_live_..." },
});
const data = await response.json();
console.log(data);

Tool: list_tables
Arguments: company_id (id, optional)
Access: read on Raw data
Hints: readOnly=true, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, list tables with company_id cmp_14f5."

The request

Parameters

What comes back

Errors that apply

Related