This article covers reporting metrics that can be calculated using Intercom's REST API and CSV exports. Use it to build custom reports from raw API data, troubleshoot discrepancies between your workspace dashboard and CSV exports, or understand how metrics map across Intercom's different reporting systems. This article is intended for developers and data analysts who access Intercom conversation data programmatically or via bulk export.
Not all metrics can be calculated via the REST API, as some data is not included in the API endpoints. Check your Intercom plan to confirm that REST API access and CSV exports are available on your subscription.
Important definitions and terms:
Visible conversation part = Conversation part that is visible to the customer.
Human admin conversation part = Conversation part created by a teammate. Excludes parts created by Simple automations (Intercom's rule-based bot), Facebook and GitHub bots.
All durations are in seconds.
The durations in the API exclude office hours.
The durations in Elasticsearch that exclude office hours have a suffix
_ooo.
REST API metrics
The following tables list REST API metrics available on the Intercom conversations endpoint. Use these to build custom reports or query conversation data programmatically.
Timestamps
first_contact_reply_at
| Timestamp for the earliest of the following contact events. All other timestamps in this section are measured relative to this value:
|
first_assignment_at | Timestamp of the first assignment conversation part after first_contact_reply_at |
first_admin_reply_at | Timestamp of the first visible human admin conversation part after first_contact_reply_at |
first_close_at | Timestamp of the first close conversation part after first_contact_reply_at |
last_assignment_at | Timestamp of the last assignment conversation part after first_contact_reply_at |
last_assignment_admin_reply_at | Timestamp of the last assignment conversation part after first_contact_reply_at and before first_admin_reply_at |
last_contact_reply_at
| Timestamp for the latest of the following contact events:
|
last_admin_reply_at | Timestamp of the last user visible human admin conversation part after first_contact_reply_at |
last_close_at | Timestamp of the last close conversation part after first_contact_reply_at |
count_reopens | Number of reopens after first_contact_reply_at |
count_assignments | Number of assignments after first_contact_reply_at |
count_conversation_parts | Total number of conversation parts |
The following durations are all expressed in seconds and exclude office hours. These are REST API fields on the conversation object.
Durations
time_to_assignment | |
time_to_admin_reply | |
time_to_first_close | |
time_to_last_close | |
reply_times | List of reply times for a conversation. A reply time is the time difference between a visible human admin conversation part and the previous visible conversation part if that part was created by the customer. |
The following sections list equivalent metrics available in Intercom's Elasticsearch reporting pipelines. Elasticsearch is the data store that powers Intercom's built-in reporting charts. Where a metric is defined as 'Same as [API metric]', the calculation is identical — only the field name differs.
Elasticsearch is the data store that powers Intercom's built-in reporting charts. Intercom maintains two Elasticsearch pipelines — a newer pipeline used by current reporting features and a legacy pipeline used by older charts. The sections below list the equivalent Elasticsearch field names for the REST API metrics defined above. Where a field is defined as 'Same as [API field]', the underlying calculation is identical — only the field name differs.
Elasticsearch - new pipeline
These are Elasticsearch new pipeline timestamp fields. They map directly to the REST API timestamps above and power the current reporting charts in your workspace.
Timestamps
started_at | Same as first_contact_reply_at (REST API) — timestamp for the earliest text conversation part from a user, attribute collected part, or UserMessage. |
first_response_at | Same as first_admin_reply_at (REST API) — timestamp of the first visible human admin conversation part after first_contact_reply_at. |
last_closed_at | Same as last_close_at (REST API) — timestamp of the last close conversation part after first_contact_reply_at. |
last_closed_by_human_at | Timestamp of the last close conversation part by a human after started_at |
These are Elasticsearch new pipeline duration fields, expressed in seconds. They correspond to the REST API duration metrics above.
Durations
time_to_last_close | Same as time_to_last_close (REST API) — duration from first_contact_reply_at to last_close_at, in seconds. |
time_to_last_close_by_human | |
first_response_time | Same as time_to_admin_reply (REST API) — duration from first_contact_reply_at to first_admin_reply_at, in seconds. |
Elasticsearch - legacy pipeline
New inbound conversations
The 'New inbound conversations' chart in your Intercom Reports shows data for conversations linked to UserMessage messages (conversations initiated by a customer). The selected timeframe is applied to the conversation created_at timestamp, not the message thread created_at.
CSV export
The CSV export downloads data linked to the message threads in the selected timeframe. It includes all conversations across all message types, making it broader than individual reporting charts in your workspace.
For example, the 'New inbound conversations' chart in Intercom Reports shows only conversations linked to a UserMessage message type, whereas the CSV export includes conversations linked to all message types. This is why totals in the CSV export may not match individual chart figures.
Important: Comparing CSV export results with your workspace dashboard charts may not yield the same results since message thread created_at is not the same as the conversation created_at.
Examples
The following scenarios illustrate how reporting metrics are calculated across different conversation timelines. Each scenario shows how timestamps and durations are applied depending on when events occur in a conversation.
Scenario 1: Single open-close cycle
Scenario 1: a timeline example showing how first_contact_reply_at, first_admin_reply_at, and related timestamps are calculated for a straightforward conversation with a single open-close cycle.
Scenario 2: Conversation reopened after closing
Scenario 2: a timeline example showing how metrics are calculated when a conversation is reopened after being closed, affecting last_close_at, count_reopens, and time_to_last_close.
Scenario 3: Multiple assignments and admin replies
Scenario 3: a timeline example showing how metrics are calculated when there are multiple assignments and admin replies before the conversation is closed, affecting time_to_assignment and last_assignment_admin_reply_at.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts