Discrepancy in total_count between ListConversations and Search Conversations endpoints | Community
Skip to main content

Hello everyone,

I'm trying to understand how the total_count value is calculated for the ListConversations and Search Conversations endpoints, as I'm observing some unexpected behavior.

When I use the ListConversations endpoint, the total_count seems stable and returns a very high number (around 7 million). However, when I use the Search Conversations endpoint with filters, the total_count is significantly lower and seems unreliable.

Here are my specific questions and observations:

  1. I added a filter to search for all conversations before today's date, but the result was much smaller (from 7M to around 350k). If I try an earlier date, it returns the same result. Is it possible that the Search endpoint only returns a limited dataset of the entire content?

  2. Is the Search endpoint reliable for calculating total_count? For example, when I use the following query to search for conversations within a specific date range:

    JSON

     

    {
      "query": {
        "operator": "AND",
        "value": [
          {
            "field": "created_at",
            "operator": ">",
            "value": "1756800000"
          },
          {
            "field": "created_at",
            "operator": "<",
            "value": "1758844799"
          }
        ]
      },
      "pagination": {
        "per_page": 50
      }
    }

    It only returns one conversation, when there should be hundreds of thousands, considering I have about 6k new conversations daily.

Any insight into how these endpoints handle the total_count and if there's a recommended way to get an accurate count for filtered searches would be greatly appreciated.

Thank you!

Hey ​@pocho23, Emily here from Support Engineering at Intercom 👋🏼

 

You’re right to compare the two endpoints - their numbers should line up conceptually, but they’re counting different things and a couple of gotchas can make Search look much lower. Here’s a clear way to think about it and how to get accurate counts.

 

What total_count means on each endpoint

  • ListConversations: The response’s total_count is the total number of conversations in your workspace for that list request (i.e., without any filters beyond what the endpoint inherently applies). It’s expected to be stable and high on large workspaces. “total_count” is “a count of the total number of objects.”

  • Search Conversations: The response’s total_count is the number of conversations that match the filter(s) in your search query. It is also “a count of the total number of objects.” There’s no documented sampling or subset restriction—Search returns the count of all items matching the query and uses cursor pagination to page through them.

 

Recommended approach to get accurate filtered counts at scale

If you want an accurate count for a date-bounded search:

  • Use the Search Conversations endpoint and rely on total_count for your filter. This is the intended approach, shown throughout the pagination and reporting docs; you can page through if you need the actual items, but you can extract the count directly from the first page.

  • For reporting over large timespans, the Intercom “Build your own reports” guide recommends doing searches in time “buckets” (e.g., daily or weekly) and summing or aggregating the counts yourself. This pattern is both performant and reliable at scale, and the examples explicitly use total_count as the count for each query bucket.

  • If you only need high-level totals (e.g., open/closed/assigned) without arbitrary filters, consider the Counts API for conversation totals. It returns workspace-level open/closed/assigned metrics and is purpose-built for those rollups (not for custom-filtered ranges, but handy for validating your overall totals).

Terms & ConditionsAccessibility statement