> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Search threads

> Find Gmail conversations with Gmail search syntax and return their thread IDs.

`searchThreads` searches Gmail conversations using the same query syntax as Gmail's search box. Use it when each matching conversation should appear once, even if several messages in that conversation match.

The action returns identifiers only. Pass a result to [Get thread](/reference/integrations/gmail/actions/get-thread) to retrieve and parse every message in the conversation.

## Example

```ts automations/find-customer-threads.automation.ts theme={null}
import { automation } from "automate.ax"
import { searchThreads } from "automate.ax/gmail"

export default automation("Find recent customer threads", () => {
  searchThreads({
    query: "from:customer@example.com newer_than:90d",
    limit: 50,
  })
})
```

## Inputs

| Property           | Type                                              | Required | Default         | Description                                                                                   |
| ------------------ | ------------------------------------------------- | -------- | --------------- | --------------------------------------------------------------------------------------------- |
| `query`            | `string`                                          | No       | —               | Query using Gmail search-box syntax. An omitted or empty query does not filter by query text. |
| `labelIds`         | `string[]`                                        | No       | —               | Gmail label IDs that every returned thread must carry. These are IDs, not display names.      |
| `includeSpamTrash` | `boolean`                                         | No       | `false`         | Whether threads in Spam and Trash may match.                                                  |
| `limit`            | `number`                                          | No       | `100`           | Maximum total results. Must be an integer from 1 to 10,000.                                   |
| `account`          | `string \| IntegrationAccountReference<"google">` | No       | Project default | Google account binding to search.                                                             |

Each input can also be a compatible `Signal` from an earlier trigger or action.

## Output

Returns a `Signal<ThreadIdentifier[]>`:

```ts theme={null}
interface ThreadIdentifier {
  threadId: string
}
```

The action fetches additional Gmail result pages internally until it reaches `limit` or exhausts the search.

<Note>
  Choose [Search
  messages](/reference/integrations/gmail/actions/search-messages) when you need
  a separate result for each matching email. Choose `searchThreads` when you
  need one result per conversation.
</Note>