> ## 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.

# Gaps

> Identify missing knowledge and capabilities in your AI

## What are Gaps?

Gaps represent questions your AI couldn't answer or actions it couldn't perform. Thunder automatically detects these moments and categorizes them, helping you understand where your AI falls short.

There are two types of gaps:

| Type              | Description                                      | Example                                                                  |
| ----------------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
| **Knowledge Gap** | Information the AI doesn't know but users expect | "What's your refund policy?" when the AI wasn't trained on refund info   |
| **Tool Gap**      | Actions the AI can't perform but users request   | "Can you book an appointment for me?" when the AI can't access calendars |

## Why Gaps Matter

Gaps are your roadmap for AI improvement. They tell you:

* **What knowledge to add** - Specific topics users ask about that your AI can't answer
* **What tools to build** - Capabilities users expect but don't exist yet
* **How often they occur** - Which gaps affect the most users
* **Recent trends** - What users are asking about now

## Gap Metrics

| Metric     | Description                                                                     |
| ---------- | ------------------------------------------------------------------------------- |
| `sessions` | Conversations where this gap was detected                                       |
| `users`    | Unique users who encountered this gap                                           |
| `messages` | Number of times this gap occurred (a gap can appear multiple times per session) |

## Querying Gaps

### Most Common Gaps

Find your most frequent unanswered questions:

```bash theme={null}
curl "https://api.usethunder.com/v1/query?\
groupBy=GAP&\
instanceId=your-instance-id&\
dateRange.start=2024-01-01T00:00:00Z&\
dateRange.end=2024-01-31T23:59:59Z&\
timeGranularity=ALL&\
fields=sessions,users,messages&\
sort.field=messages&\
sort.order=DESC&\
limit=20" \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "elements": [
    {
      "dimensions": {
        "gap": {
          "id": "gap-uuid",
          "name": "Refund policy details",
          "description": "Users asking about refund timeframes and conditions",
          "gapType": "KNOWLEDGE"
        }
      },
      "fields": {
        "sessions": 156,
        "users": 143,
        "messages": 234
      }
    },
    {
      "dimensions": {
        "gap": {
          "id": "gap-uuid-2",
          "name": "Appointment booking",
          "description": "Users wanting to schedule appointments",
          "gapType": "TOOL"
        }
      },
      "fields": {
        "sessions": 89,
        "users": 82,
        "messages": 112
      }
    }
  ],
  "pagination": { "total": 47, "limit": 20, "offset": 0 }
}
```

### Filter by Gap Type

Find only knowledge gaps or only tool gaps:

```bash theme={null}
# Knowledge gaps only
curl "https://api.usethunder.com/v1/query?\
groupBy=GAP&\
instanceId=your-instance-id&\
gapType=KNOWLEDGE&\
dateRange.start=2024-01-01T00:00:00Z&\
dateRange.end=2024-01-31T23:59:59Z&\
timeGranularity=ALL&\
fields=sessions,messages&\
sort.field=sessions&\
sort.order=DESC" \
  -H "x-api-key: YOUR_API_KEY"
```

```bash theme={null}
# Tool gaps only
curl "https://api.usethunder.com/v1/query?\
groupBy=GAP&\
instanceId=your-instance-id&\
gapType=TOOL&\
dateRange.start=2024-01-01T00:00:00Z&\
dateRange.end=2024-01-31T23:59:59Z&\
timeGranularity=ALL&\
fields=sessions,messages&\
sort.field=sessions&\
sort.order=DESC" \
  -H "x-api-key: YOUR_API_KEY"
```

### Recent Gaps

Find gaps from the last 7 days to see what users are asking about now:

```bash theme={null}
curl "https://api.usethunder.com/v1/query?\
groupBy=GAP&\
instanceId=your-instance-id&\
dateRange.start=2024-01-24T00:00:00Z&\
dateRange.end=2024-01-31T23:59:59Z&\
timeGranularity=ALL&\
fields=sessions,users,messages&\
sort.field=sessions&\
sort.order=DESC" \
  -H "x-api-key: YOUR_API_KEY"
```

### Gap Trends Over Time

Track how gaps change week over week:

```bash theme={null}
curl "https://api.usethunder.com/v1/query?\
groupBy=GAP&\
instanceId=your-instance-id&\
dateRange.start=2024-01-01T00:00:00Z&\
dateRange.end=2024-01-31T23:59:59Z&\
timeGranularity=WEEK&\
fields=sessions,messages" \
  -H "x-api-key: YOUR_API_KEY"
```

## Finding Sessions with Gaps

See the actual conversations where a gap occurred:

```bash theme={null}
curl "https://api.usethunder.com/v1/query?\
groupBy=SESSION&\
instanceId=your-instance-id&\
gapIds=gap-uuid-here&\
dateRange.start=2024-01-01T00:00:00Z&\
dateRange.end=2024-01-31T23:59:59Z&\
timeGranularity=ALL&\
fields=messages,sat,dsat&\
dimensionFields=title,summary,topics" \
  -H "x-api-key: YOUR_API_KEY"
```

This returns all sessions where that specific gap was detected, along with the conversation summary and related topics.

## Use Cases

<CardGroup cols={2}>
  <Card title="Knowledge Base Priorities" icon="book">
    Use knowledge gap frequency to decide what documentation or training data to add first.
  </Card>

  <Card title="Feature Roadmap" icon="road">
    Tool gaps show what integrations and capabilities users want most.
  </Card>

  <Card title="Measure AI Improvement" icon="chart-line">
    Track gap frequency over time to verify that updates are working.
  </Card>

  <Card title="Topic Correlation" icon="diagram-project">
    Cross-reference gaps with topics to understand which subject areas have the most missing information.
  </Card>
</CardGroup>

***

See [Querying Metrics](/guides/querying-metrics) for more query patterns and the full field reference.