Sessions

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:

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:

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:

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:

{
  "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:

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

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.

Include user IDs

Always include userId in your messages so Thunder can track end user engagement and link sessions to users.

Ingest complete conversations

For best analysis results, ingest both user and assistant messages. Thunder needs both sides to detect satisfaction signals and gaps.

Getting Started

Fundamentals

Features

Guides

Security

What is a Session?

Session Structure

Creating Sessions

Adding Messages to Existing Sessions

Querying Sessions

Filtering Sessions

Best Practices

​What is a Session?

​Session Structure

​Creating Sessions

​Adding Messages to Existing Sessions

​Querying Sessions

​Filtering Sessions

​Best Practices

What is a Session?

Session Structure

Creating Sessions

Adding Messages to Existing Sessions

Querying Sessions

Filtering Sessions

Best Practices