# Tickets, stats and team

Every endpoint on this page is read-only, and read-only keys can call them. Specialists can call all of them except team stats. The shared rules for authentication, rate limits and errors are in [Authentication and conventions](api-overview.md). IDs and content in the examples are made up.

## List assist tickets

::: endpoint GET /api/tenants/{tenant_id}/tickets
:::

Returns open assist tickets and those closed in the last seven days, up to 500 rows in a single array. Open tickets get priority when selecting rows for the limit.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `filter` | string | No | `all` (default), `pool` for unclaimed tickets, `mine` for tickets you claimed |

The main fields of each ticket:

| Field | Description |
| --- | --- |
| `ticket_id`, `conversation_id` | The ticket and its conversation |
| `public_title` | The ticket title shown in Desk |
| `status` | `created` open, `accepted` claimed, `working` in progress, `completed` resolved, `failed` couldn't resolve, `cancelled` |
| `assignee_id` | Who claimed it; empty when nobody has |
| `task_version` | The ticket version, usable as `expected_task_version` when writing a note |
| `due_at` | Due time |
| `created_at`, `closed_at` | When it was opened and closed |

:::: example
```bash [curl]
curl "$AILO_BASE_URL/api/tenants/demo-shop/tickets?filter=pool" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
```

```json [200 response (excerpt)]
[
  {
    "ticket_id": "t_51",
    "conversation_id": "c_8f21",
    "public_title": "Verify deposit",
    "status": "created",
    "assignee_id": null,
    "task_version": 1,
    "due_at": "2026-11-12T10:30:00Z",
    "created_at": "2026-11-12T09:32:00Z",
    "closed_at": null
  }
]
```
::::

## Search assist tickets

::: endpoint GET /api/tenants/{tenant_id}/tickets/search
:::

Searches retained assist tickets in the organization, including tickets closed more than seven days ago. Requires `tickets.manage` and the `tickets:read` API key scope.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Ticket title, ticket ID, customer name shown in Desk, or conversation ID |
| `status` | string | No | `pool`, `working`, `waiting`, `resolved`, or `attached` |
| `mine` | boolean | No | `true` keeps only tickets assigned to the authenticated member. Defaults to `false`. |
| `cursor` | string | No | The previous page's `next_cursor`. Keep the same query and filters. |
| `limit` | integer | No | 1–50, default 50 |

The response has `tickets` in the same row format as the list, ordered by the newest ticket activity the caller can see. `next_cursor` is null on the last page.

## Team stats

::: endpoint GET /api/tenants/{tenant_id}/stats
:::

The same numbers as the Stats page in Desk: resolution rate, how Specialists joined, waiting, first response, assist tickets, satisfaction and more.

It needs the permission to view stats, which only admins and owners have by default; without it you get `403 permission_denied`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `window` | string | No | `today`, `7d` (default) or `30d` |
| `from`, `to` | string | No | Custom days as `YYYY-MM-DD`, both included; give both, at most 90 days, not after today; they replace `window` |
| `site_id` | string | No | One site only; without it, the whole organization |

A "day" follows the default time zone of the organization's business hours, or UTC when none is set; `timezone` in the response names it. The main fields:

| Field | Description |
| --- | --- |
| `resolution` | Resolution rate: ended conversations split into resolved by Ailo, resolved with a Specialist, and unresolved |
| `modes` | How Specialists joined: `assist` conversations with an assist ticket, `transfer` transfers that were picked up, `specialist_led` times a Specialist started serving on their own |
| `wait` | Transfer requests, accepted, withdrawn by the customer and expired, with the median wait in seconds |
| `first_response` | First response |
| `tickets` | Assist tickets created, claimed, resolved, couldn't resolve and cancelled, with median handling time |
| `rating`, `ratings_by` | Customer ratings, split by who was serving when the customer rated |
| `summary`, `previous`, `delta` | This period's headline numbers, the same for the period before, and the change |
| `daily` | Numbers by day |
| `truncated` | `true` when there were too many conversations and only part was counted |

There are more fields; the actual response is the reference. A malformed range or one longer than 90 days returns `400 bad_request`.

:::: example
```bash [curl]
curl "$AILO_BASE_URL/api/tenants/demo-shop/stats?window=30d&site_id=site_th" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
```
::::

## The team right now

::: endpoint GET /api/tenants/{tenant_id}/team/now
:::

Returns how many conversations Ailo is serving right now: `{ "ai_serving": 4 }`.

:::: example
```bash [curl]
curl "$AILO_BASE_URL/api/tenants/demo-shop/team/now" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
```
::::

## Confirmation counts

::: endpoint GET /api/tenants/{tenant_id}/confirmation-counts
:::

Ailo rates its own confidence on every reply. This endpoint counts a period's replies by confidence, and how each one ended: sent directly, approved by a teammate, edited then sent, answered by a teammate, turned into serving, auto-sent on timeout, or discarded.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `from`, `to` | string | No | ISO times in UTC ending in `Z`. Without `to`, this Monday 00:00 UTC; without `from`, 7 days before `to`. At most 31 days |

Returns `total`, `levels` (`high`, `medium` and `low`, each with its count and outcomes) and `settings` (how many replies would need a teammate's confirmation with the confirmation setting at less, default or more).

:::: example
```bash [curl]
curl "$AILO_BASE_URL/api/tenants/demo-shop/confirmation-counts?from=2026-11-02T00:00:00Z&to=2026-11-09T00:00:00Z" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
```
::::

## Members

::: endpoint GET /api/tenants/{tenant_id}/agents
:::

Returns the organization's members as an array. Each has fields such as `agent_id`, `display_name`, `team`, `presence` (`online`, `focus` for focus on tickets, `away`), `capacity` (how many conversations they can serve at once), `open_count` (conversations they serve now) and `inactive_count` (how many of those are inactive).

:::: example
```bash [curl]
curl "$AILO_BASE_URL/api/tenants/demo-shop/agents" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
```

```json [200 response (excerpt)]
[
  {
    "agent_id": "a_mia",
    "display_name": "Mia",
    "team": "Payments",
    "presence": "online",
    "capacity": 3,
    "open_count": 2,
    "inactive_count": 0
  }
]
```
::::

## Sites

::: endpoint GET /api/tenants/{tenant_id}/sites
:::

Returns the organization's sites: `{ "ok": true, "sites": [ … ] }`, each with `site_id`, `name` and `is_default` (whether it is the default site).

:::: example
```bash [curl]
curl "$AILO_BASE_URL/api/tenants/demo-shop/sites" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
```

```json [200 response]
{ "ok": true, "sites": [{ "site_id": "site_th", "name": "Thailand", "is_default": true }] }
```
::::
