> ## Documentation Index
> Fetch the complete documentation index at: https://www.text.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the Reports API

> Retrieve Text reporting data for custom analysis, external dashboards, and automated reporting workflows.

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

## Before you start

For access requirements and API version support, see:

<p>
  <Icon icon="file" /> [Authorization](/docs/authentication/overview)

  <br />

  <Icon icon="file" /> [Scopes](/docs/authentication/scopes)

  <br />

  <Icon icon="file" /> [API versioning](/docs/key-concepts/api-versioning)
</p>

## Reports resources

| Resource                                                 | Description                                                      |
| -------------------------------------------------------- | ---------------------------------------------------------------- |
| [Chats](/docs/api/reports/v3.6/chats/duration)                | Analyze conversation activity, handling, and outcomes over time. |
| [Agents](/docs/api/reports/v3.6/agents/availability)          | Compare agent availability and performance over time.            |
| [Customers](/docs/api/reports/v3.6/customers/unique-visitors) | Analyze customer visits and queue activity.                      |
| [Tags](/docs/api/reports/v3.6/tags/chat-usage)                | Measure how often selected tags appear on chats.                 |

## Related APIs

| If you need to                                                        | Use                                |
| --------------------------------------------------------------------- | ---------------------------------- |
| Retrieve individual chats and events instead of report results        | [Agent Chat API](/docs/api/agent-chat/) |
| Receive notifications when events occur instead of requesting reports | [Webhooks](/docs/api/webhooks/v3.6/)    |

For a broader comparison, see [Data and analytics APIs](/docs/api-overview/data-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.

```json title="Combine chat report filters" theme={null}
{
  "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.

<Accordion title="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.

  ```json title="Filter by pre-chat form submissions" theme={null}
  {
    "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]
          }
        }
      ]
    }
  }
  ```
</Accordion>