Intercom API for reporting | Community
Skip to main content

Hi there

 

I am hoping to create some dashboards based off of our product’s intercom data that surfaces insights about # of tickets created and average conversation rating.  High level mockup of the dashboard:

 

Diving into the intercom API, it looks like the only way to get aggregate data is by calling the search APIs and checking the total_count property.  This is un-ideal in the case of average satisfaction score where I would need to query 5 times for each satisfaction score value per data bucket.  If I have a time series with 12 month buckets, that would mean I would have to query Intercom 70 times per dashboard render.  Is there a better alternative to accomplish this?  I saw reference of a reporting feature coming to the API at some point: 


Also, what is intercom’s data retention policy?  Can I expect to be able to retrieve all of our intercom data or is there a cut-off?

​@richard-govwell, I’ve asked our internal AI resources to come up with some alternative approach to your reporting challenge. Here is the answer based on our Intercom codebase. 

Current API Limitations & Your Concerns
 

Yes, the search API approach you've identified (using total_count from multiple queries) is currently the primary method available, and it does create exactly the scaling issues you've outlined:

For satisfaction scores across 12 months, you'd need 5 queries per month (one for each rating value 1-5) = 60 queries

Plus queries for ticket counts = potentially 70+ API calls per dashboard render

This approach is inefficient and not scalable for real-time dashboards


Better Alternatives Available

While the current public API has these limitations, there are more efficient approaches that can be used for aggregated metrics:


1. Satisfaction Score Calculation

Rather than querying each rating value separately, satisfaction scores can be calculated more efficiently by:
  • Using aggregation queries that process all rating values in a single request
  • Implementing client-side calculation logic that processes the raw conversation data
  • Leveraging scripted aggregations where supported to calculate percentages server-side

2. Optimized Data Collection

For dashboard use cases, consider:
  • Implementing a caching layer that pre-computes metrics at regular intervals
  • Using webhook events to maintain your own aggregated data store
  • Batching multiple time periods into fewer, more comprehensive queries

Upcoming Reporting API

You're correct about the new reporting API in development. Based on public communications from Intercom, there is indeed work happening on:
  • Enhanced Reporting APIs - Designed to provide better parity with in-app reporting metrics
  • Aggregated Metrics Endpoints - That will eliminate the need for multiple search calls
  • Time-series Data Support - With proper bucketing for dashboard use cases
The team has acknowledged the known discrepancies between the current API and in-app reporting and is working to address these gaps.


Data Retention Policy

Regarding data retention, Intercom's general approach includes:
  • Conversation Data: Retained according to your plan's data retention policy
  • Historical Metrics: Available for reporting purposes within the retention window
  • Data Compliance: Subject to GDPR/CCPA deletion requests and legal requirements
For your specific retention period, I'd recommend:
  • Checking your plan documentation for specific retention periods
  • Contacting Intercom support for clarification on your account's data availability
  • Testing API calls with older date ranges to confirm data availability

Recommendations

  • Short-term: Implement caching/pre-computation to reduce real-time API load
  • Medium-term: Monitor for the new reporting API release announcements
  • Alternative: Build a webhook-based aggregation system that processes data incrementally
  • Optimization: Batch time periods and use broader date ranges to minimize query count
The limitations you've identified are well-known in the developer community, and the upcoming reporting API should significantly improve the experience for dashboard builders like yourself.
Keep an eye on the Intercom Developer Blog for updates on the new reporting API release.
Terms & ConditionsAccessibility statement