---
title: "Search Threads"
method: GET
path: "/v0/threads/search"
tags: ["Threads"]
---

# Search Threads

`GET /v0/threads/search`

Full-text search across threads in the organization, ranked by
relevance. The query is matched against senders, recipients, and
subject (substring) and the message body (tokenized full text). Spam,
trash, blocked, and unauthenticated threads are always excluded.
`limit` cannot exceed 100.

## Query parameters

- `q` string, required — Full-text search query. Matched against the sender, recipients, and subject (substring) and the message body (tokenized full text).
- `limit` integer — Limit of number of items returned.
- `page_token` string — Page token for pagination.
- `before` string, date-time — Timestamp before which to filter by.
- `after` string, date-time — Timestamp after which to filter by.

## Response `200`

- SearchThreadsResponse
  - `count` integer, required — Number of items returned.
  - `limit` integer — Limit of number of items returned.
  - `next_page_token` string — Page token for pagination.
  - `threads` SearchThreadItem[], required — Ordered by relevance, best match first.
    - `inbox_id` string, required — The ID of the inbox.
    - `thread_id` string, required — ID of thread.
    - `labels` string[], required — Labels of thread.
    - `timestamp` string, date-time, required — Timestamp of last sent or received message.
    - `received_timestamp` string, date-time — Timestamp of last received message.
    - `sent_timestamp` string, date-time — Timestamp of last sent message.
    - `senders` string[], required — Senders in thread. In format `username@domain.com` or `Display Name <username@domain.com>`.
    - `recipients` string[], required — Recipients in thread. In format `username@domain.com` or `Display Name <username@domain.com>`.
    - `subject` string — Subject of thread.
    - `preview` string — Text preview of last message in thread.
    - `attachments` Attachment[] — Attachments in thread.
      - `attachment_id` string, required — ID of attachment.
      - `filename` string — Filename of attachment.
      - `size` integer, required — Size of attachment in bytes.
      - `content_type` string — Content type of attachment.
      - `content_disposition` 'inline' | 'attachment' — Content disposition of attachment.
      - `content_id` string — Content ID of attachment.
    - `last_message_id` string, required — ID of last message in thread.
    - `message_count` integer, required — Number of messages in thread.
    - `size` integer, required — Size of thread in bytes.
    - `updated_at` string, date-time, required — Time at which thread was last updated.
    - `created_at` string, date-time, required — Time at which thread was created.

## Other responses

- `400`
- `404`

---

[API](https://skmtc.net/agentmail-to/apis/api.md) · [All operations](https://skmtc.net/agentmail-to/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentmail-to/api/versions/394ddcdd9c29/schema)