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

# Sessions

> Understanding how Thunder organizes and analyzes conversations

## What is a Session?

A session represents a single conversation between your AI and a user. Each session contains one or more messages exchanged back and forth, and Thunder analyzes these messages to extract insights.

Sessions are the primary unit of analysis in Thunder. When you query metrics, you're typically aggregating data across sessions - counting how many sessions discussed a topic, how many contained satisfaction signals, or how many revealed knowledge gaps.

## Session Structure

Each session has:

| Field          | Description                                       |
| -------------- | ------------------------------------------------- |
| `sessionId`    | Unique identifier (UUID)                          |
| `instanceId`   | The instance this session belongs to              |
| `endUserId`    | The user who initiated the conversation           |
| `title`        | Auto-generated title summarizing the conversation |
| `summary`      | Brief summary of what was discussed               |
| `language`     | Detected language of the conversation             |
| `createdAt`    | When the session started                          |
| `lastActiveAt` | When the last message was added                   |

## Creating Sessions

Sessions are created automatically when you ingest messages. If you don't provide a `sessionId`, Thunder creates one for you:

```bash theme={null}
curl -X POST https://api.usethunder.com/v1/ingest \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "your-instance-id",
    "messages": [
      { "role": "user", "content": "Hello!", "userId": "user_123" },
      { "role": "assistant", "content": "Hi there!" }
    ]
  }'
```

The response includes the `sessionId` - store this to add more messages later.

## Adding Messages to Existing Sessions

Include the `sessionId` to continue a conversation:

```bash theme={null}
curl -X POST https://api.usethunder.com/v1/ingest \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "your-instance-id",
    "sessionId": "existing-session-id",
    "messages": [
      { "role": "user", "content": "Can you help me more?", "userId": "user_123" },
      { "role": "assistant", "content": "Of course!" }
    ]
  }'
```

## Querying Sessions

Use `groupBy=SESSION` to get per-session metrics:

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

This returns each session with its metrics and metadata:

```json theme={null}
{
  "elements": [
    {
      "dimensions": {
        "session": {
          "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "title": "Password Reset Help",
          "summary": "User needed help resetting their password...",
          "topics": [{ "id": "...", "name": "Account Management" }]
        }
      },
      "fields": {
        "messages": 5,
        "sat": 1,
        "dsat": 0,
        "repeatedRequests": 0
      }
    }
  ]
}
```

## Filtering Sessions

Filter sessions by various criteria:

| Filter               | Description                                       |
| -------------------- | ------------------------------------------------- |
| `topicIds`           | Sessions that discussed specific topics           |
| `signalIds`          | Sessions containing specific satisfaction signals |
| `gapIds`             | Sessions where specific gaps were detected        |
| `repeatedRequestIds` | Sessions with specific repeated requests          |
| `language`           | Sessions in a specific language                   |

Example - find all sessions about a specific topic:

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

## Best Practices

<AccordionGroup>
  <Accordion title="Use consistent session IDs">
    If you're managing session IDs on your end, use UUIDs and ensure the same conversation always uses the same session ID. This ensures accurate analysis.
  </Accordion>

  <Accordion title="Include user IDs">
    Always include `userId` in your messages so Thunder can track end user engagement and link sessions to users.
  </Accordion>

  <Accordion title="Ingest complete conversations">
    For best analysis results, ingest both user and assistant messages. Thunder needs both sides to detect satisfaction signals and gaps.
  </Accordion>
</AccordionGroup>