List events

The request

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

GET /api/v1/events

The key needs the Jobs 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
`cursor`	number, in the query	No	The next from your last answer. Leave it out the first time to get the latest changes and a cursor to start from.	`88400`
`company_id`	id, in the query	No	One company. Default: every company the credential reaches.	`cmp_14f5`
`limit`	number, in the query	No	1 to 200. Default 50.	`50`

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 cursor (optional, number) company_id (optional, id) limit (optional, number)

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

What comes back

items, oldest first: position, event (a type from the Event catalog), at, by (a person, or "Reporting laptop, for Ariel T." when a key acted), job (id, number, company_id) and data, a few plain facts about the change. next: send it as cursor to continue; it is always safe to keep, even with no items. more: true when there is more to read now. Only jobs this credential reaches appear, and jobs in Trash never do. Money amounts, customer details and message text are never carried: read the job for those.

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[].position`	whole number	Where the change landed in the event log. Pass it as `after` on a read to see your own write.
`items[].event`	text	The kind of event, as a code.
`items[].at`	time (ISO 8601, with offset)	The moment it happened. Carries its offset from UTC; `Z` is UTC.
`items[].by`	text	Who did it. A key shows as its name, then "for" and the member it acts as.
`items[].job`	object	The job.
`items[].job.id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`items[].job.number`	whole number	The number people say out loud, such as the job number.
`items[].job.company_id`	id (text)	The id of the company.
`items[].data`	object	The data.
`items[].data.status`	text	The job status.
`items[].data.status_slug`	text	The status slug.
`items[].data.previous_status`	text	The previous status.
`next`	whole number	The cursor for the next page, or null on the last page. Pass it back as `cursor`.
`more`	true or false	The more.

Reading in order

Call with the cursor you were given, handle the items, keep next. A call with no cursor returns the latest changes, not all of history. The feed holds back a change until the app has finished recording it, so a change you just made may show a moment later: use after= with the position your command answered to wait for it.

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 event types: Every kind of change the Changes feed can carry, in plain words, and the facts each one puts in data.
The same records in the app: the Jobs panel.
How the API fits together: the model, API keys, errors and the MCP server.

Answer cURL Python JavaScript Your AI

{
  "items": [
    {
      "position": 88402,
      "event": "job.status_changed",
      "at": "2026-10-26T14:02:11Z",
      "by": "Reporting laptop, for Ariel T.",
      "job": {
        "id": "job_1138",
        "number": 1138,
        "company_id": "cmp_14f5"
      },
      "data": {
        "status": "Dispatched",
        "status_slug": "dispatched",
        "previous_status": "Scheduled"
      }
    }
  ],
  "next": 88402,
  "more": false
}

curl "https://api.headhoncho.app/api/v1/events?cursor=88400&company_id=cmp_14f5" \
  -H "Authorization: Bearer hh_live_..."

import requests

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

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

Tool: list_events
Arguments: cursor (number, optional), company_id (id, optional), limit (number, optional)
Access: read on Jobs
Hints: readOnly=true, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, list events with cursor 88400."