Skip to main content

​
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:
FieldDescription
sessionIdUnique identifier (UUID)
instanceIdThe instance this session belongs to
endUserIdThe user who initiated the conversation
titleAuto-generated title summarizing the conversation
summaryBrief summary of what was discussed
languageDetected language of the conversation
createdAtWhen the session started
lastActiveAtWhen 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:
FilterDescription
topicIdsSessions that discussed specific topics
signalIdsSessions containing specific satisfaction signals
gapIdsSessions where specific gaps were detected
repeatedRequestIdsSessions with specific repeated requests
languageSessions 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

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.
Always include userId in your messages so Thunder can track end user engagement and link sessions to users.
For best analysis results, ingest both user and assistant messages. Thunder needs both sides to detect satisfaction signals and gaps.