Intercom API (unofficial showcase)
POST/conversations/search

Search conversations

Searches conversations using filters on searchable conversation attributes. Provide a query filter expression and use pagination to control result size; pages default to 20 results and can contain up to 150. Use the starting_after cursor from the response to fetch subsequent pages.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

3 parameters · 2 body fields
include_monitorsbooleanoptional
Whether to include `monitor_evaluations` in each conversation when QA monitor results flagged it. Defaults to false when omitted.
Default:false
include_scorecardsbooleanoptional
Whether to include QA `scorecards` in each conversation. Defaults to false when omitted.
Default:false
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Search criteria and optional cursor-based pagination settings.

queryobjectrequired
The required filter expression, supplied as a single filter or a combination of filters.
paginationobjectoptional
Cursor-based pagination settings. Use `per_page` to set the page size and `starting_after` to continue from a previous page.

1 status code
200Returns matching conversation objects, the total result count, and cursor-based pagination metadata.
typestringoptional
Always conversation.list
Allowed:conversation.list
conversationsarray<ConversationListItem>optional
The list of conversation objects
total_countintegeroptional
A count of the total number of objects.
pagesobjectoptional
Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

Error handling

The query body field is required, and each filter's operator must be compatible with the field's value type. You can nest at most two filter levels and include at most 15 filters in each AND or OR group; per_page defaults to 20 and cannot exceed 150.