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

# Querying stats

> Query company insights with POST /v2/insights/stats. The request is a nested JSON body and does not change any data.

> [!WARNING]
>
> **The [query stats endpoint](https://docs.theymes.com/api-reference/authenticated-endpoints-api-key/query-stats.md) does not change any data.**
>
> `POST` is used because the query is a nested JSON body. A successful call only reads stats and returns them.

Query insights for the company that owns your API key.

```http theme={null}
POST https://api.theymes.com/v2/insights/stats
Authorization: Bearer <YOUR_API_KEY>
```

The [API reference](https://docs.theymes.com/api-reference/authenticated-endpoints-api-key/query-stats.md) lists every metric, filter, and breakdown. This page shows how a query is put together.

## Request

| Field | Required | Description |
| - | - | - |
| `metrics` | Yes | One or more metrics. Each value in a result row follows this order. |
| `timeframe` | Yes | One time range. |
| `filters` | No | Filters applied to every metric. |
| `breakdown` | No | One dimension. Each row's `breakdown` is that dimension's display name. |
| `segment` | No | A second dimension, returned on each row as `segment`. |

A metric can also carry its own `filters`. Those apply to that metric only, together with the shared filters.

`timeframe`, `breakdown`, and `segment` are single objects. Send one timeframe, and at most one breakdown and one segment.

### Timeframe

Preset values are `TODAY`, `PAST_7_DAYS`, `PAST_30_DAYS`, `PAST_90_DAYS`, and `PAST_365_DAYS`. Preset ranges include the current day.

A custom range sets `from` and `to` to a `YYYY-MM-DD` date, or to an object with `date` and `hours`:

```json theme={null}
{ "type": "CUSTOM", "from": "2026-01-01", "to": { "date": "2026-01-31", "hours": 18 } }
```

### Filters

The operators depend on the kind of value the filter takes.

**Select.** Pick from a list. `value` is an array, including when you send one value. `is` matches any listed value. `is-not` matches none of them.

**String.** `value` is text. `is` is an exact match, and `is-not` is any other text. `contains` matches when the text includes the value, and `not-contains` matches when it does not.

**Multiselect.** A ticket can have several values. `value` is an array.

* `include-any` matches when at least one listed value is present.
* `include-all` matches when every listed value is present.
* `exclude-any` matches when none of the listed values are present.
* `exclude-all` matches when at least one listed value is missing.

**Boolean.** Use `is` with `true` or `false`.

Some filters also accept `is-set` and `is-not-set` with `"value": null`. Those match when a value is present, or when it is missing.

## Examples

A timeframe plus shared filters:

```json theme={null}
{
  "metrics": [{ "type": "CLOSED_TICKETS" }],
  "timeframe": { "type": "PAST_30_DAYS" },
  "filters": [
    { "type": "status", "op": "is", "value": ["closed"] },
    { "type": "app", "op": "is", "value": ["APP_ID"] }
  ]
}
```

Two metrics, a metric-specific filter, and a breakdown:

```json theme={null}
{
  "metrics": [
    { "type": "CREATED_TICKETS" },
    {
      "type": "CSAT",
      "filters": [{ "type": "channel", "op": "is", "value": ["chat"] }]
    }
  ],
  "timeframe": { "type": "PAST_7_DAYS" },
  "breakdown": { "type": "APP" }
}
```

A matching response echoes the query and returns one number per metric. `breakdown` on each row is the display name, and `timeframe` on each row is the resolved range:

```json theme={null}
{
  "metrics": [
    { "type": "CREATED_TICKETS" },
    {
      "type": "CSAT",
      "filters": [{ "type": "channel", "op": "is", "value": ["chat"] }]
    }
  ],
  "timeframe": { "type": "PAST_7_DAYS" },
  "breakdown": { "type": "APP" },
  "stats": [
    {
      "timeframe": { "type": "PAST_7_DAYS", "from": "2026-10-19", "to": "2026-10-26" },
      "metrics": [12, 4.5],
      "breakdown": "Example app"
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.