# List tickets (/api-reference/tickets/listTickets)

## GET /api/v1/tickets/

Operation ID: `listTickets`
List tickets
Newest change first by default. Filter by status, type, priority, lead, category, team or tag.

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `page` | query | no | Page number, from 1. |
| `limit` | query | no | Tickets per page (1-200). |
| `search` | query | no | Ticket ref, words in the subject or description, or the lead's name or phone. |
| `status` | query | no | `open`, `in_progress`, `waiting_on_customer`, `resolved` or `closed`; `open` also matches `in_progress` and `waiting_on_customer`. |
| `type` | query | no | `support` or `sales_followup`. |
| `leadId` | query | no | Only this lead's tickets. |
| `sourceCallId` | query | no | Only tickets opened from this call. |
| `unassigned` | query | no | Only tickets nobody is assigned to. |
| `priority` | query | no | `low`, `normal`, `high` or `urgent`. |
| `tag` | query | no | Only tickets with this tag. |
| `categoryId` | query | no | Category id, or `none` for tickets without one. |
| `teamId` | query | no | Team id, or `none` for tickets without one. |
| `sort` | query | no | `updated` (default), `created`, `due`, `priority` or `status`. |
| `dir` | query | no | `asc` or `desc`. |

### Responses

#### 200 OK

Example (example):

```json
{
  "pagination": {
    "currentPage": 1,
    "hasNextPage": false,
    "hasPreviousPage": false,
    "itemsPerPage": 25,
    "totalCapped": false,
    "totalItems": 1,
    "totalPages": 1
  },
  "sort": {
    "dir": "desc",
    "key": "updated"
  },
  "success": true,
  "tickets": [
    {
      "activityCount": 1,
      "assignedToUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
      "assigneeEmail": "priya@example.com",
      "assigneeName": "Priya Nair",
      "assigneeNames": [
        "Priya Nair"
      ],
      "assignees": [
        {
          "assignedAt": "2026-01-15T09:30:02+00:00",
          "email": "priya@example.com",
          "name": "Priya Nair",
          "userId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f"
        }
      ],
      "categoryId": "3b9f1d7e-6c2a-4e85-a0d4-7f1e2c3b4a56",
      "categoryName": "Delivery",
      "createdAt": "2026-01-15T09:30:00+00:00",
      "createdByUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
      "description": "Customer says the parcel was marked delivered but never arrived.",
      "dueAt": "2026-01-16T09:30:00+00:00",
      "id": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90",
      "leadId": "a41e7c2d-8f35-4b09-b6d2-93c0e5f1a7b8",
      "leadName": "Asha Verma",
      "leadPhone": "+919812345678",
      "merchantId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
      "overdue": false,
      "priority": "normal",
      "ref": "T-5F0C9A3E",
      "sla": {
        "firstResponse": {
          "dueAt": "2026-01-15T13:30:00+00:00",
          "state": "ok",
          "warnAt": "2026-01-15T12:30:00+00:00"
        },
        "paused": false,
        "resolution": {
          "dueAt": "2026-01-16T09:30:00+00:00",
          "state": "ok",
          "warnAt": "2026-01-16T05:30:00+00:00"
        }
      },
      "source": "manual",
      "status": "open",
      "subject": "Order #1042 not delivered",
      "tags": [
        "order-1042"
      ],
      "teamId": "e7a1c3d5-9b2f-4d68-8a0c-2e4f6a8b0c1d",
      "teamName": "Customer care",
      "type": "support",
      "updatedAt": "2026-01-15T09:30:00+00:00",
      "version": 1
    }
  ]
}
```

#### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`.

Example (The API key has expired.):

```json
{
  "detail": "The API key has expired.",
  "error": {
    "code": "api_key_expired",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_expired",
    "message": "The API key has expired.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (The API key is invalid or has been revoked.):

```json
{
  "detail": "The API key is invalid or has been revoked.",
  "error": {
    "code": "invalid_api_key",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (Authentication required.):

```json
{
  "detail": "Authentication required.",
  "error": {
    "code": "unauthenticated",
    "docUrl": "https://docs.callmitra.ai/errors/unauthenticated",
    "message": "Authentication required.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

#### 403 Forbidden: `api_key_scope_denied`, `permission_denied`.

Example (The API key does not have the scope required for this request.):

```json
{
  "detail": "The API key does not have the scope required for this request.",
  "error": {
    "code": "api_key_scope_denied",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied",
    "message": "The API key does not have the scope required for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (You do not have permission to perform this action.):

```json
{
  "detail": "You do not have permission to perform this action.",
  "error": {
    "code": "permission_denied",
    "docUrl": "https://docs.callmitra.ai/errors/permission_denied",
    "message": "You do not have permission to perform this action.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

#### 422 Invalid parameters: `parameter_invalid`.

Example (One or more parameters are invalid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "parameter_invalid",
    "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
    "message": "One or more parameters are invalid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 429 Too many requests: `rate_limit_exceeded`.

Example (Too many requests. Slow down and retry later.):

```json
{
  "detail": "Too many requests. Slow down and retry later.",
  "error": {
    "code": "rate_limit_exceeded",
    "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry later.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

#### 500 Server error: `internal_error`.

Example (Something went wrong on our side.):

```json
{
  "detail": "Something went wrong on our side.",
  "error": {
    "code": "internal_error",
    "docUrl": "https://docs.callmitra.ai/errors/internal_error",
    "message": "Something went wrong on our side.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

### Error codes

- [`api_key_expired`](/errors/api_key_expired)
- [`invalid_api_key`](/errors/invalid_api_key)
- [`unauthenticated`](/errors/unauthenticated)
- [`api_key_scope_denied`](/errors/api_key_scope_denied)
- [`permission_denied`](/errors/permission_denied)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`internal_error`](/errors/internal_error)
