> For the complete documentation index, see [llms.txt](https://mava.gitbook.io/mava-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mava.gitbook.io/mava-docs/webhooks-and-api/api/fetch-tickets.md). # Fetch Tickets ### Endpoint ``` GET /api/tickets ``` ### Authentication * Requires API token authentication (`x-auth-token` header) * Subject to rate limiting (90 requests per 30 seconds) ### Query Parameters | Parameter | Type | Required | Default | Description | | ----------------- | ------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------- | | `startDate` | string | **Yes** | — | Start of date range (ISO 8601, e.g. `2026-01-01` or `2026-01-01T00:00:00.000Z`) | | `endDate` | string | **Yes** | — | End of date range (exclusive). Must be after startDate. Max range: 1 year | | `limit` | integer | No | `50` | Number of tickets per page (1–100) | | `skip` | integer | No | `0` | Number of tickets to skip (for pagination) | | `status` | string or string\[] | No | — | Filter by status. Values: `Open`, `Resolved`, `Pending`, `Waiting` | | `assignedTo` | string or string\[] | No | — | Filter by agent IDs. Use `Unassigned` for unassigned tickets | | `category` | string or string\[] | No | — | Filter by category ID(s) | | `tags` | string or string\[] | No | — | Filter by tag ID(s) | | `csatValues` | string or string\[] | No | — | Filter by CSAT rating. Values: `1`–`5` or `no-rating` | | `origin` | string or string\[] | No | — | Filter by ticket origin. Values: `web`, `discord`, `telegram`, `telegram-group`, `email` | | `sortBy` | string | No | `createdAt` | Sort field. Values: `createdAt`, `status`, `priority`, `sourceType`, `assignedTo`, `category`, `resolutionTime` | | `sortOrder` | string | No | `desc` | Sort direction: `asc` or `desc` | | `includeMessages` | boolean | No | `false` | When `true`, includes the full message thread for each ticket | ### Response **Success (200 OK)** ```json { "tickets": [ { "_id": "6650a1b2c3d4e5f678901234", "createdAt": "2026-03-15T10:30:00.000Z", "updatedAt": "2026-03-16T14:22:00.000Z", "status": "Resolved", "priority": 2, "sourceType": "discord", "resolutionTime": 100920000, "assignedTo": { "_id": "6650b2c3d4e5f67890123456", "name": "Jane Smith" }, "category": { "_id": "6650c3d4e5f678901234567a", "name": "Billing" }, "tags": [ { "_id": "6650d4e5f678901234567890", "name": "VIP" } ], "csat": { "value": 5 }, "aiStatus": "resolved", "discordUsers": [ { "discordAuthorId": "123456789", "name": "user#1234" } ], "attributes": [ { "attributeId": "6650e5f6789012345678abcd", "name": "Plan", "content": "Enterprise" } ], "customer": { "_id": "6650f6789012345678abcdef", "email": "user@example.com", "attributes": [ { "attributeId": "665012345678abcdef012345", "name": "Company", "content": "Acme Inc" } ] }, "messages": [ { "_id": "665112345678abcdef012345", "content": "I need help with my billing", "senderType": "customer", "senderName": "user#1234", "messageType": "ExternalMessage", "createdAt": "2026-03-15T10:30:00.000Z", "attachments": [] }, { "_id": "665212345678abcdef012345", "content": "Let me look into that for you", "senderType": "agent", "senderName": null, "messageType": "ExternalMessage", "createdAt": "2026-03-15T11:00:00.000Z", "attachments": [] } ] } ], "count": 285, "pagination": { "limit": 50, "skip": 0, "hasMore": true } } ``` #### Response Fields | Field | Description | | ----------------------- | -------------------------------------------------------------------------------- | | `resolutionTime` | Milliseconds between creation and resolution. `null` if not resolved | | `csat` | Customer satisfaction rating (1-5). `null` if no rating or telegram-group ticket | | `aiStatus` | AI handling status. `null` for telegram-group tickets | | `discordUsers` | Discord usernames associated with the ticket. Empty for non-Discord tickets | | `customer` | Customer details with custom attributes. `null` for telegram-group tickets | | `messages` | Only included when `includeMessages=true`. Sorted oldest-first | | `messages[].senderType` | `customer`, `agent`, or `system` | | `messages[].senderName` | Discord username when available, otherwise `null` | | `pagination.hasMore` | `true` if more tickets exist beyond the current page | #### Error Responses **Missing or invalid date range (400)** ```json { "error": "MISSING_DATE_RANGE" } ``` ```json { "error": "INVALID_DATE_RANGE" } ``` Returned when: * `startDate` or `endDate` is missing * Dates are not valid ISO 8601 format * `endDate` is before or equal to `startDate` * Date range exceeds 1 year \ **Invalid limit (400)** ```json { "error": "INVALID_LIMIT" } ``` Returned when `limit` is not an integer between 1 and 100. \ **Invalid skip (400)** ```json { "error": "INVALID_SKIP" } ``` Returned when `skip` is negative. \ **Unsupported sort field (400)** ```json { "error": "UNSUPPORTED_SORT_FIELD" } ``` Returned when `sortBy` is not one of the supported values. \ **Unsupported sort order (400)** ```json { "error": "UNSUPPORTED_SORT_ORDER" } ``` Returned when `sortOrder` is not `asc` or `desc`. \ **Unauthorized (401)** Returned when the API key is missing or invalid. **Too Many Requests (429)** Returned when the rate limit is exceeded. The API allows up to 90 requests per 30 seconds per API key. **Internal Server Error (500)** ```json { "error": "Internal server error" } ``` ### Code Examples **Curl - Basic usage** ```bash curl -X GET "https://gateway.mava.app/api/tickets?startDate=2026-01-01&endDate=2026-04-01&limit=20" \ -H "x-auth-token: YOUR_API_KEY" ``` \ **Curl - With filters and messages** ```bash curl -X GET "https://gateway.mava.app/api/tickets?startDate=2026-01-01&endDate=2026-04-01&status=Open&status=Pending&assignedTo=Unassigned&origin=discord&sortBy=priority&sortOrder=desc&includeMessages=true&limit=10" \ -H "x-auth-token: YOUR_API_KEY" ``` \ **NodeJS - Basic usage** ```javascript const params = new URLSearchParams({ startDate: '2026-01-01', endDate: '2026-04-01', limit: '20', includeMessages: 'true', }); const response = await fetch(`https://gateway.mava.app/api/tickets?${params}`, { method: 'GET', headers: { 'x-auth-token': 'YOUR_API_KEY', }, }); const data = await response.json(); console.log(`Found ${data.count} tickets`); ``` \ **NodeJS - Paginate through all results** ```javascript const limit = 50; let skip = 0; let allTickets = []; while (true) { const params = new URLSearchParams({ startDate: '2026-01-01', endDate: '2026-04-01', limit: String(limit), skip: String(skip), }); const res = await fetch(`https://gateway.mava.app/api/tickets?${params}`, { headers: { 'x-auth-token': 'YOUR_API_KEY' }, }); const page = await res.json(); allTickets.push(...page.tickets); if (!page.pagination.hasMore) break; skip += limit; } console.log(`Total tickets fetched: ${allTickets.length}`); ``` #### Filtering by multiple values To filter by multiple values for the same parameter, repeat the parameter: ``` ?status=Open&status=Pending ?origin=discord&origin=email ?csatValues=4&csatValues=5&csatValues=no-rating ``` #### Pagination Use `skip` and `limit` to paginate through results. The response includes `pagination.hasMore` to indicate whether more pages exist. 1. Start with `skip=0` 2. After each response, if `hasMore` is `true`, increase `skip` by `limit` 3. Repeat until `hasMore` is `false` The `count` field always reflects the total number of matching tickets across all pages. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://mava.gitbook.io/mava-docs/webhooks-and-api/api/fetch-tickets.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.