--- title: "Find messages by query" url: https://docs.gleap.ai/en/reference/rest-api/get-messages method: GET path: "/messages" api: "API Reference" tag: "Messages" operationId: "GetMessages" updatedAt: "2026-11-01T18:40:15.677Z" language: en --- # Find messages by query `GET https://api.gleap.io/v3/messages` Get messages by query with support for filtering and pagination. **Filtering:** - Filter by ticket: `ticket=507f1f77bcf86cd799439011`. Any identifier `GET /tickets/{ticketId}` accepts works here too — the human-facing ticket number shown in the dashboard (`ticket=143790`), the 24-char ObjectId, or the shareToken. - Filter by type: `type=TEXT` or `type=TEXT,NOTE` (comma-separated values match any; bracket syntax such as `type[$in]=...` is NOT supported) - Filter by bot messages: `bot=true` or `bot=false` - Filter by date range: `createdAt>=2024-01-01&createdAt<=2024-12-31` **Ordering:** Messages within a response are always oldest-first (ascending `createdAt`); the sort order is not configurable. **Pagination:** - Cursor mode (recommended): pass `paginated=true` to receive `{ items, hasMore, nextBefore }`. Pages walk backwards in time: the first page holds the newest `limit` messages, and `before=` (the previous `nextBefore`, which is the oldest message of that page) fetches the next older page. Keep going until `hasMore` is `false`, then sort by `createdAt` on your side. `skip` is ignored in this mode; `limit` defaults to 30 and is clamped to 1-100. If the cursor message was deleted between two calls, the request fails with 409; restart from the newest page. - Legacy mode (no `paginated`): returns a flat array; `limit` defaults to 1000 and values above 100 are clamped to 100; `skip` is applied. **Exporting a full conversation:** Filter by `ticket` rather than by `bot`. `bot=true` selects messages exchanged with the AI bot, so on a conversation that was handed over to a human it omits the agent's replies — `ticket={ticketId}` returns every top-level message. Thread replies are not part of the main feed: a message with replies carries a `thread` object (`replyCount`, `lastReplyAt`), so call `GET /messages/{messageId}/thread` only for those. Ticket history is not part of it either (see below). Which conversations still exist is governed by retention — AI-only (`type=BOT`) conversations are deleted about 33 days after they are created, see GET /tickets. **Edits and deletes:** a message's `updatedAt` changes when it is edited, and also on other updates such as reactions or read status; there is no separate "edited" flag. Deleted messages are removed permanently (with their thread replies) and send no webhook or event; compare message IDs on re-fetch to detect them. Neither changes the ticket's `updatedAt`. **Attachments:** file URLs in the response are signed and expire after about one day; no authentication is needed while they are valid. Download files you want to keep, and re-fetch the message for a fresh URL. **Ticket history:** Since August 2026 this endpoint returns conversation messages only. Audit entries — `FEEDBACK_UPDATED` (status, assignee, team, priority, type, tag, title changes, …) and workflow/system entries — are no longer part of the response; filtering by those types returns an empty result. Fetch them from `GET /tickets/{ticketId}/history`, which returns them in the same message-compatible shape. **Translation:** - `language=es` returns messages translated into the given language. Requires the project setting 'translate customer messages'; only conversation messages (`TEXT`, `USER_TEXT`, `NOTE`, `BOT`, `BOT_REPLY`, `SHARED_COMMENT`) are translated, and messages already in the target language are returned unchanged. ## Authorization - `Authorization` (header, required): `Bearer ` ## Query parameters - `paginated` (boolean): - Set to `true` for cursor mode: returns `{ items, hasMore, nextBefore }` - `before` (string): - Cursor for the next older page (the previous response's `nextBefore`); only with `paginated=true` - `limit` (number): - Maximum number of messages to return. Cursor mode: default 30, clamped to 1-100. Legacy mode: default 1000, values above 100 are clamped to 100. - `showHistory` (boolean): - Deprecated, accepted and ignored. Ticket-history entries are served by `GET /tickets/{ticketId}/history`. ## Headers - `project` (string, required) ## Example request ```bash curl --request GET \ --url https://api.gleap.io/v3/messages \ --header 'Authorization: Bearer ' \ --header 'project: ' ``` ## Responses ### 200 (`application/json`) Ok ```json [ { "id": "507f1f77bcf86cd799439015", "ticket": "507f1f77bcf86cd799439011", "type": "TEXT", "data": { "content": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "This is a sample message content." } ] } ] } }, "comment": "This is a sample message content.", "bot": false, "user": { "id": "507f1f77bcf86cd799439012", "email": "support@example.com", "firstName": "John", "lastName": "Doe" }, "session": { "_id": "507f1f77bcf86cd799439013", "id": "507f1f77bcf86cd799439013", "email": "user@example.com" }, "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z", "index": 0 }, { "id": "507f1f77bcf86cd799439016", "ticket": "507f1f77bcf86cd799439011", "type": "TEXT", "data": { "content": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Thank you for the update!" } ] } ] } }, "comment": "Thank you for the update!", "bot": false, "user": { "id": "507f1f77bcf86cd799439017", "email": "user@example.com", "firstName": "Jane", "lastName": "Smith" }, "session": { "_id": "507f1f77bcf86cd799439013", "id": "507f1f77bcf86cd799439013", "email": "user@example.com" }, "createdAt": "2024-01-15T11:00:00.000Z", "updatedAt": "2024-01-15T11:00:00.000Z", "index": 1 } ] ```