---
name: "ticket_list"
area: "helpdesk"
title: "List tickets"
price: "free"
method: "POST"
url: "https://api.conecto.chat/v1/tools/ticket_list"
mcp_server: "https://api.conecto.chat/mcp/helpdesk"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/helpdesk/ticket_list"
---

# List tickets (`ticket_list`)

Tickets, newest activity first, filtered by status, priority, requester, tag, field or contact, or as a work queue.

Tickets, newest activity first, by status (default: open and pending), priority, requester, tag, custom field, CRM contact or company, words in the subject or request, or activity since a time. A view gives a work queue instead: waiting_on_us (open, no reply since the customer last wrote; longest waiting first), waiting_on_customer (pending), overdue (an SLA target missed; most overdue first), at_risk (an SLA target due within within_minutes), unassigned, or mine (assigned to the calling bot). Free.

Price: Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads. A call that fails costs nothing.

## Use it when

To see what needs an answer (a queue like waiting_on_us or overdue), or one customer's tickets.

## Say this to your agent

> Which support tickets are still waiting on us? Longest wait first.

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `view` | string | no |  | `"unassigned"`, `"mine"`, `"waiting_on_us"`, `"waiting_on_customer"`, `"overdue"`, `"at_risk"` |  |
| `status` | string | no |  | `"open"`, `"pending"`, `"resolved"`, `"all"` |  |
| `priority` | string | no |  | `"low"`, `"normal"`, `"high"`, `"urgent"` |  |
| `requester` | string | no | Up to 254 characters. |  |  |
| `query` | string | no | Up to 200 characters. |  |  |
| `tag` | string | no | Up to 40 characters. |  |  |
| `fields` | object | no | Only tickets with these custom field values, e.g. {"order_id": "1042"}. |  |  |
| `contact_id` | integer | no | At least 1. |  |  |
| `company_id` | integer | no | At least 1. |  |  |
| `since` | string | no | ISO 8601: activity at or after this time. Up to 40 characters. |  |  |
| `within_minutes` | integer | no | 1 to 10,080. |  | `60` |
| `limit` | integer | no | 1 to 100. |  | `25` |

## Example

Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon.

MCP: call `ticket_list` on the MCP server `https://api.conecto.chat/mcp/helpdesk` with these arguments:

```json
{
  "view": "waiting_on_us"
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/ticket_list \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"view": "waiting_on_us"}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "ticket_list",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.00",
  "balance_usd": "$19.75",
  "result": {
    "tickets": [
      {
        "number": 1,
        "subject": "Scratch on the Tabor's top tube",
        "status": "open",
        "priority": "high",
        "category": "Damaged delivery",
        "tags": [
          "damage"
        ],
        "requester_email": "paul.hoffmann@example.com",
        "requester_name": "Paul Hoffmann",
        "contact_id": null,
        "company_id": null,
        "source": "api",
        "channel": "api",
        "assigned_to": null,
        "waiting_on": "us",
        "sla": null,
        "merged_into": null,
        "created_at": "2026-10-14T08:00:00+00:00",
        "last_activity_at": "2026-10-14T08:00:00+00:00",
        "first_reply_at": null,
        "resolved_at": null
      }
    ],
    "count": 1
  }
}
```

`result`: Up to 100 tickets, each with its number, subject, status, priority, category, tags, requester, contact and company, channel, assignee, waiting_on, SLA state and times, and how many.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `invalid_input` | 400 | since is not an ISO 8601 time. | Send it like 2026-10-12T09:00:00Z. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [ticket_get](https://conecto.chat/tools/helpdesk/ticket_get.md): One ticket with its request, every reply, customer message and note, its fields, SLA state and rating. Free up to 1,000,000 reads a month.
- [ticket_create](https://conecto.chat/tools/helpdesk/ticket_create.md): Opens a support ticket for a customer request; the customer is emailed only if you ask. $0.01 a call.
- [ticket_reply](https://conecto.chat/tools/helpdesk/ticket_reply.md): Emails the requester a reply in the ticket's thread, with files if needed, or adds a private note, and can set the status. $0.05 a call.
- [ticket_update](https://conecto.chat/tools/helpdesk/ticket_update.md): Changes a ticket's status, priority, category, subject, tags, fields, assignee, or the CRM records it is about. $0.01 a call.
- [ticket_merge](https://conecto.chat/tools/helpdesk/ticket_merge.md): Merges a duplicate ticket into another: its messages, notes, email threads, tags and fields move over. $0.01 a call.
- [ticket_connect_inbox](https://conecto.chat/tools/helpdesk/ticket_connect_inbox.md): Makes an inbox a support inbox: every new email to it opens a ticket, and replies stay in its thread. $0.001 a call.
- [ticket_save_template](https://conecto.chat/tools/helpdesk/ticket_save_template.md): Saves a canned reply under a name, with the status and tags it applies whenever it is sent. $0.001 a call.
- [ticket_list_templates](https://conecto.chat/tools/helpdesk/ticket_list_templates.md): Every saved reply with its text, status and tags. Free up to 1,000,000 reads a month.
- [ticket_delete_template](https://conecto.chat/tools/helpdesk/ticket_delete_template.md): Deletes a saved reply by name. $0.001 a call.
- [ticket_get_settings](https://conecto.chat/tools/helpdesk/ticket_get_settings.md): The help desk's SLA targets, auto-close, satisfaction survey setting and support inboxes. Free up to 1,000,000 reads a month.
- [ticket_update_settings](https://conecto.chat/tools/helpdesk/ticket_update_settings.md): Sets the SLA targets per priority, auto-close and the satisfaction survey. $0.001 a call.
- [ticket_report](https://conecto.chat/tools/helpdesk/ticket_report.md): How support went over the last days: volumes, backlog, response and resolution times, SLA results, ratings, and tickets by channel, priority and tag. Free up to 1,000,000 reads a month.