# List agency jobs

List agency jobs is a read in the HeadHoncho API. 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.

Page: https://headhoncho.app/docs/api/list_agency_jobs | Part of the HeadHoncho API docs: https://headhoncho.app/docs/api | Machine-readable: https://headhoncho.app/docs/api/openapi.json | Everything in one file: https://headhoncho.app/docs/api/llms-full.txt

## The request

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

`GET /api/v1/agency/jobs`

The key needs the **Statistics and marketing** area at **read**. An answered call costs 1 credit; a refusal costs nothing. See [credits](https://headhoncho.app/docs/api/errors#credits).

Send your key as `Authorization: Bearer hh_live_...`. See [API keys](https://headhoncho.app/docs/api/keys).

## Parameters

| Name | Kind | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `from` | date, in the query | No | First day. Default: 45 days ago. | `2026-09-11` |
| `to` | date, in the query | No | Last day, included. Default: today. At most a year from from. | `2026-10-26` |
| `company_id` | id, in the query | No | One company. Default: every company the credential reaches. | `cmp_14f5` |
| `page` | number, in the query | No | Default 1. | `1` |
| `per_page` | number, in the query | No | 1 to 500. Default 200. | `200` |

## 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.

Paste your key on the web page and it fills a cURL line and a fetch line with your key and the example values. The page never sends the key anywhere. The same lines with a placeholder key are under Examples below.

## What comes back

from, to, timezone, date_format, columns (the agency's headings), keys, count (rows in all), page, per_page, next (the next page number or null) and rows in the sixteen columns, oldest first. Money is text with two decimals, as the agency's file prints it.

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. |
| `timezone` | text | The timezone. |
| `date_format` | text | The date format. |
| `columns` | list of text | The columns. |
| `keys` | list of text | The keys. |
| `count` | whole number | How many match in all, across every page. |
| `page` | whole number | The page number, starting at 1. |
| `per_page` | whole number | The per page. |
| `next` | value or null | The cursor for the next page, or null on the last page. Pass it back as `cursor`. |
| `rows` | list of objects | The rows. |
| `rows[].ticket` | whole number | The job number the ticket shows. |
| `rows[].status` | text | The job status. |
| `rows[].customer_phone` | text | The customer's phone number. Hidden when the key hides personal details. |
| `rows[].start_date` | date and time (company time zone) | The start date. |
| `rows[].close_date` | date and time (company time zone) | The close date. |
| `rows[].total` | money (decimal as text) | The total, in the company's currency. |
| `rows[].company_total` | money (decimal as text) | The company total. In the company's currency. |
| `rows[].job_source` | text | Where the job came from, such as Google Ads. |
| `rows[].gclid` | text | The Google click id the call or visit carried. |
| `rows[].callrail_call_id` | id (text) | The id of the callrail call. |
| `rows[].campaign_id` | id (text) | The ad platform's id for the campaign. |
| `rows[].callrail_call_start` | date and time (company time zone) | The callrail call start. |
| `rows[].lead_source` | text | How the lead first reached the business. |
| `rows[].paid_date` | date (YYYY-MM-DD) | The paid date. |
| `rows[].time_zone` | text | The company's time zone name, such as America/Chicago. |
| `rows[].callrail_source_name` | text | The callrail source name. |

## Same rows, now on a key

This is the feed an agency pulled with its own token, with the same sixteen columns under the same names as the file and the webhook. Only the door changed: a key with access to Statistics and marketing reads it.

## Masked until the match is paid

gclid and callrail_call_id print whole once the job's match is paid for: the Google Click IDs report is turned on in Statistics › Reports and the job's one credit is paid (jobs opened before the first Turn on are free). Until then both print masked, their first and last characters around an ellipsis. The webhook and the daily file follow the same rule.

## Errors that apply

| Code | Status | What it means |
| --- | --- | --- |
| [`missing_key`](https://headhoncho.app/docs/api/errors#missing_key) | 401 | Send your key as Authorization: Bearer hh_live_... |
| [`unknown_key`](https://headhoncho.app/docs/api/errors#unknown_key) | 401 | That key is not one we issued, or it was revoked. |
| [`no_access`](https://headhoncho.app/docs/api/errors#no_access) | 403 | This credential does not reach that. Ask the person who made it for access. |
| [`not_found`](https://headhoncho.app/docs/api/errors#not_found) | 404 | No such record in the companies this credential reaches. |
| [`out_of_scope`](https://headhoncho.app/docs/api/errors#out_of_scope) | 404 | No such company in the companies this credential reaches. |
| [`invalid`](https://headhoncho.app/docs/api/errors#invalid) | 422 | Some fields were refused. See fields. |
| [`no_credits`](https://headhoncho.app/docs/api/errors#no_credits) | 402 | Out of credits. Top up on Settings › Credits, or turn on auto top-up. |

## Related

- [List ad accounts](https://headhoncho.app/docs/api/list_ad_accounts): The ad accounts and call tracking each company has connected, and how each one is doing.
- [List campaigns](https://headhoncho.app/docs/api/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.
- [Get agency feed](https://headhoncho.app/docs/api/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](https://headhoncho.app/docs/statistics).
- How the API fits together: [the model](https://headhoncho.app/docs/api/model), [API keys](https://headhoncho.app/docs/api/keys), [errors](https://headhoncho.app/docs/api/errors) and [the MCP server](https://headhoncho.app/docs/api/mcp).

## Examples

### Answer

```json
{
  "from": "2026-09-11",
  "to": "2026-10-26",
  "timezone": "America/Chicago",
  "date_format": "YYYY-MM-DD HH:MM",
  "columns": [
    "Ticket",
    "Status",
    "Customer phone (E.164)",
    "Start date",
    "Close date",
    "Total",
    "Company total",
    "Job source",
    "gclid",
    "CallRail call id",
    "Campaign ID",
    "CallRail call start",
    "Lead source",
    "Paid date",
    "Time zone",
    "CallRail source name"
  ],
  "keys": [
    "ticket",
    "status",
    "customer_phone",
    "start_date",
    "close_date",
    "total",
    "company_total",
    "job_source",
    "gclid",
    "callrail_call_id",
    "campaign_id",
    "callrail_call_start",
    "lead_source",
    "paid_date",
    "time_zone",
    "callrail_source_name"
  ],
  "count": 1,
  "page": 1,
  "per_page": 200,
  "next": null,
  "rows": [
    {
      "ticket": 1138,
      "status": "Closed",
      "customer_phone": "+12175550142",
      "start_date": "2026-10-11 13:25",
      "close_date": "2026-10-16 11:40",
      "total": "1450.00",
      "company_total": "610.00",
      "job_source": "Google Ads",
      "gclid": "Cj0KCQjw...",
      "callrail_call_id": "CAL8f2e1",
      "campaign_id": "2184930112",
      "callrail_call_start": "2026-10-11 13:22",
      "lead_source": "call",
      "paid_date": "2026-10-16",
      "time_zone": "America/Chicago",
      "callrail_source_name": "pool - google ads"
    }
  ]
}
```

### cURL

```bash
curl "https://api.headhoncho.app/api/v1/agency/jobs?from=2026-09-11&to=2026-10-26" \
  -H "Authorization: Bearer hh_live_..."
```

### Python

```python
import requests

response = requests.get(
    "https://api.headhoncho.app/api/v1/agency/jobs",
    headers={"Authorization": "Bearer hh_live_..."},
    params={
        "from": "2026-09-11",
        "to": "2026-10-26",
    },
)
response.raise_for_status()
print(response.json())
```

### JavaScript

```javascript
const response = await fetch("https://api.headhoncho.app/api/v1/agency/jobs?from=2026-09-11&to=2026-10-26", {
  headers: { Authorization: "Bearer hh_live_..." },
});
const data = await response.json();
console.log(data);
```

### Your AI

```text
Tool: list_agency_jobs
Arguments: from (date, optional), to (date, optional), company_id (id, optional), page (number, optional), per_page (number, optional)
Access: read on Statistics and marketing
Hints: readOnly=true, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, list agency jobs with from 2026-09-11."
```