---
title: List Tickets (LLM)
description: GET /tickets - list tickets with filters and keyset pagination.
---

# GET /tickets

List tickets on the token's desk, newest first. Scope: `tickets:read`.

Full URL: `https://<your-desk>.headoni.app/api/v1/tickets`
Auth header: `Authorization: Bearer hd_<secret>`

Returns summaries only (no message bodies). Use `GET /tickets/{id}` for full content.

## Query Parameters

| param | type | required | default | notes |
| --- | --- | --- | --- | --- |
| requesterEmail | string | no | - | exact match on the requester's primary email; lowercased server-side |
| status | string | no | - | keyword `open` / `awaiting_reply` / `resolved` / `closed`, OR a numeric status id |
| limit | int | no | 25 | 1 to 100 |
| cursor | string | no | - | a ticket id; returns rows with id < cursor (keyset page) |

## Example Request

```bash
curl "https://acme.headoni.app/api/v1/tickets?status=open&limit=20" \
  -H "Authorization: Bearer hd_your_secret_here"
```

## Success Response

Status `200`.

```json
{
  "tickets": [
    {
      "id": "1490375649312800768",
      "number": 1247,
      "subject": "Login broken on staging",
      "priority": "high",
      "status": { "id": "1490300000000000001", "label": "Open", "internalType": "open" },
      "requester": { "email": "alice@example.com", "name": "Alice" },
      "createdAt": "2026-06-04T15:21:09.000Z",
      "updatedAt": "2026-06-04T15:40:11.000Z"
    }
  ],
  "nextCursor": "1490375649312800768"
}
```

## Pagination

- Order: ticket `id` descending (newest first).
- `nextCursor` is the id to pass back as `cursor` for the next page, or `null` at the end.
- Loop: request, read `nextCursor`, if non-null call again with `cursor=<nextCursor>`, stop when `null`.

## Errors

| status | error | cause |
| --- | --- | --- |
| 400 | invalid_query | a param failed validation; see `issues` |
| 400 | invalid_status | `status` was neither a keyword nor a numeric id |
| 401 | unauthenticated | missing or invalid token |
| 403 | insufficient_scope | token lacks `tickets:read` |