Using the Reports API - Text Documentation

The Reports API lets you retrieve the raw data available in Text reports.

Before you start

For access requirements and API version support, see:

Reports resources

Resource	Description
Chats	Analyze conversation activity, handling, and outcomes over time.
Agents	Compare agent availability and performance over time.
Customers	Analyze customer visits and queue activity.
Tags	Measure how often selected tags appear on chats.

If you need to	Use
Retrieve individual chats and events instead of report results	Agent Chat API
Receive notifications when events occur instead of requesting reports	Webhooks

For a broader comparison, see Data and analytics APIs.

Filtering reports

Report filters are nested under filters. If you omit this object, the report covers the previous 7 days. Each method schema lists the filters it supports. The following request combines several chat report filters:

Returns daily results for August in the America/New_York timezone.
Selects continuous chats assigned to groups 1 or 2 and started by customers in the United States.
Excludes chats tagged spam or test.
Requires both message and file events.
Filters by who sent the first agent response.

Combine chat report filters

{
  "distribution": "day",
  "timezone": "America/New_York",
  "filters": {
    "from": "2026-08-01T00:00:00-04:00",
    "to": "2026-08-31T23:59:59-04:00",
    "properties": {
      "routing": {
        "continuous": {
          "values": [true]
        }
      }
    },
    "groups": {
      "values": [1, 2]
    },
    "tags": {
      "exclude_values": ["spam", "test"]
    },
    "customer_countries": {
      "values": ["US"]
    },
    "event_types": {
      "values": ["message", "file"],
      "require_every_value": true
    },
    "agent_response": {
      "first": true,
      "agents": {
        "values": ["john.doe@example.com", "smith@example.com"]
      },
      "groups": {
        "values": [1, 2]
      }
    }
  }
}

Within one filter, use values to include matches or exclude_values to omit them. You cannot provide both.

Filter by form submissions

Place the time range inside the form filter when you want to select chats based on form submission time. Do not also provide filters.from and filters.to in the same request.

Filter by pre-chat form submissions

{
  "filters": {
    "forms": [
      {
        "type": "pre_chat",
        "from": "2026-08-01T00:00:00+02:00",
        "to": "2026-08-31T23:59:59+02:00",
        "values": ["163672098710307655:0"],
        "groups": {
          "values": [10]
        }
      }
    ]
  }
}

​Before you start

​Reports resources

​Related APIs

​Filtering reports

Before you start

Reports resources

Related APIs

Filtering reports