---
title: "Search Messages"
method: GET
path: "/threads/{thread_id}/messages/search"
tags: ["Messages"]
---

# Search Messages

`GET /threads/{thread_id}/messages/search`

## Request

- Base URL: `https://api.puppeteerai.com`
- URL: `https://api.puppeteerai.com/threads/{thread_id}/messages/search`
- Auth: none declared. Required headers: `Authorization`

Search for messages within a thread that contain the given text query.

## Path parameters

- `thread_id` string, required

## Query parameters

- `query` string, required: The text to search for within messages.
- `cursor` string, nullable: Base64-encoded pagination cursor. If not provided, retrieves the first batch of results.
- `limit` integer: Maximum number of search results to return per page.
- `context_size` integer: Number of messages to include before and after each match to provide conversation context.

## Headers

- `Authorization` string, required

## Response `200`

Successful Response

- SearchMessagesResponse
  - `matches` SearchMatch[], required: List of search matches with context.
    - `message_id` string, required: Unique identifier of the matched message.
    - `prev_cursor` string, nullable, required: Cursor to navigate to later messages.
    - `next_cursor` string, nullable, required: Cursor to navigate to earlier messages.
    - `context` SearchContextMessage[], required: Messages surrounding the match for context.
      - `message_id` string, required: Unique identifier of the message.
      - `role` string, required: The role of the sender: "user", "AI", or "admin".
      - `message` string, required: The message text.
      - `timestamp` integer, required: Unix timestamp (seconds) when the message was sent.
      - `conversation_id` integer, nullable: Conversation ID for grouping.
      - `conversation_end_time` string, nullable: ISO timestamp the parent conversation ended at, or null if still active.
  - `pagination` RoutersConversationsCursorPagination, required
    - `cursor` string, nullable, required: Base64-encoded cursor for the next batch of messages. Null if no more results.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/getpuppeteer/apis/puppeteer-core-api.md) - [All operations](https://skmtc.dev/getpuppeteer/apis/puppeteer-core-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getpuppeteer/apis/puppeteer-core-api/revisions/94b4e928b42f?raw)