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

# Querying Metrics

> Get the most out of Thunder's Query API

## Query Basics

The Query API returns aggregated metrics based on how you group the data. Every query requires:

| Parameter         | Description                                       |
| ----------------- | ------------------------------------------------- |
| `groupBy`         | How to aggregate data (TOPIC, SESSION, GAP, etc.) |
| `instanceId`      | Which instance to query                           |
| `dateRange.start` | Start of time range (ISO 8601)                    |
| `dateRange.end`   | End of time range (ISO 8601)                      |
| `timeGranularity` | Time bucketing (ALL, HOUR, DAY, WEEK, MONTH)      |
| `fields`          | Which metrics to return                           |

## Group By Options

| Value              | Returns                      | Use Case                          |
| ------------------ | ---------------------------- | --------------------------------- |
| `TOPIC`            | One row per topic            | What are users talking about?     |
| `SESSION`          | One row per conversation     | Drill into specific conversations |
| `END_USER`         | One row per user             | User-level engagement             |
| `GAP`              | One row per gap              | What's my AI missing?             |
| `CSAT_DSAT`        | One row per signal type      | How do users feel?                |
| `REPEATED_REQUEST` | One row per repeated request | Where do users struggle?          |

## Time Granularity

| Value   | Behavior                                    |
| ------- | ------------------------------------------- |
| `ALL`   | Single aggregation across entire date range |
| `HOUR`  | One row per hour per group                  |
| `DAY`   | One row per day per group                   |
| `WEEK`  | One row per week per group                  |
| `MONTH` | One row per month per group                 |

Use `ALL` for totals, other values for trend analysis.

## Sorting

Sort results by any numeric field:

```bash theme={null}
sort.field=sessions&sort.order=DESC
```

Available sort orders: `ASC`, `DESC`

## Filtering

### By Entity IDs

Filter results by related entities:

```bash theme={null}
# Sessions or end users about specific topics
topicIds=topic-uuid-1,topic-uuid-2

# Sessions with specific signals
signalIds=signal-uuid

# Sessions with specific gaps
gapIds=gap-uuid

# Sessions with specific repeated requests
repeatedRequestIds=rr-uuid
```

<Note>
  `topicIds` works with both `groupBy=SESSION` and `groupBy=END_USER`. Other entity filters only work with `groupBy=SESSION`.
</Note>

### By Gap Type

When querying gaps, filter by type:

```bash theme={null}
gapType=KNOWLEDGE  # or TOOL
```

### By Language

When querying sessions, filter by detected language:

```bash theme={null}
language=en  # or es, fr, de, etc.
```

## Common Query Patterns

### Top Topics This Month

```bash theme={null}
GET /v1/query?
  groupBy=TOPIC&
  instanceId=...&
  dateRange.start=2024-01-01T00:00:00Z&
  dateRange.end=2024-01-31T23:59:59Z&
  timeGranularity=ALL&
  fields=sessions,users,messages&
  sort.field=sessions&
  sort.order=DESC&
  limit=10
```

### Topic Trends Over Time

```bash theme={null}
GET /v1/query?
  groupBy=TOPIC&
  instanceId=...&
  dateRange.start=2024-01-01T00:00:00Z&
  dateRange.end=2024-01-31T23:59:59Z&
  timeGranularity=DAY&
  fields=sessions,messages
```

### Worst Performing Sessions

```bash theme={null}
GET /v1/query?
  groupBy=SESSION&
  instanceId=...&
  dateRange.start=2024-01-01T00:00:00Z&
  dateRange.end=2024-01-31T23:59:59Z&
  timeGranularity=ALL&
  fields=messages,sat,dsat,repeatedRequests&
  dimensionFields=title,summary&
  sort.field=dsat&
  sort.order=DESC&
  limit=20
```

### Knowledge Gaps by Frequency

```bash theme={null}
GET /v1/query?
  groupBy=GAP&
  instanceId=...&
  gapType=KNOWLEDGE&
  dateRange.start=2024-01-01T00:00:00Z&
  dateRange.end=2024-01-31T23:59:59Z&
  timeGranularity=ALL&
  fields=sessions,messages&
  sort.field=messages&
  sort.order=DESC
```

### Sessions About a Specific Gap

```bash theme={null}
GET /v1/query?
  groupBy=SESSION&
  instanceId=...&
  gapIds=gap-uuid&
  dateRange.start=2024-01-01T00:00:00Z&
  dateRange.end=2024-01-31T23:59:59Z&
  timeGranularity=ALL&
  fields=messages,sat,dsat&
  dimensionFields=title,summary,topics
```

## Field Reference

### Available by Group By

| Group By          | Available Fields                                                      |
| ----------------- | --------------------------------------------------------------------- |
| TOPIC             | sessions, users, messages, avgMessagesPerSession, sat, dsat, netSat   |
| SESSION           | messages, duration, lastActiveAt, sat, dsat, netSat, repeatedRequests |
| END\_USER         | sessions, messages, sat, dsat, netSat, repeatedRequests               |
| GAP               | sessions, users, messages                                             |
| CSAT\_DSAT        | sessions, users, messages                                             |
| REPEATED\_REQUEST | sessions, users, messages                                             |

### Dimension Fields

Extra metadata available for some group by options:

| Group By  | Dimension Fields                               |
| --------- | ---------------------------------------------- |
| SESSION   | title, summary, topics, language               |
| END\_USER | externalId, topTopics, createdAt, lastActiveAt |