Intercom API (unofficial showcase)
GET/conversations

List conversations

Lists conversations and returns cursor-based pagination details with the results. Use per_page to set the page size and starting_after to continue from a cursor; the default page size is 20 and the maximum is 150. Set include_monitors or include_scorecards to include the corresponding QA results on each conversation.

5 parameters
per_pageintegeroptional
Number of conversations to return per page. Defaults to 20 when omitted and has a maximum of 150.
Default:20
starting_afterstringoptional
Cursor used to retrieve the next page of conversations.
include_monitorsbooleanoptional
Set to `true` to include `monitor_evaluations` for QA monitor results that flagged each conversation. Defaults to `false` when omitted.
Default:false
include_scorecardsbooleanoptional
Set to `true` to include QA `scorecards` for 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

3 status codes
200Returns a conversation list with conversation objects, a total count, and cursor-based pagination details.
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.
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
403Returned when the API plan restricts access.

One documented failure

  • api_plan_restricted

    Active subscription needed.

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

A 401 is returned when the request is unauthorized, and a 403 when the API plan restricts access. per_page defaults to 20 and cannot exceed 150; use starting_after from the previous page to continue pagination.