Skip to main content

​
Prerequisites

​
Step 1: Get Your API Key

API keys are used to authenticate all requests to the Thunder API. You’ll need to create one from the Thunder dashboard or via the API. 
# Your API key will look something like this
x-api-key: tk_live_abc123def456...

​
Step 2: Ingest Your First Conversation

Send conversation messages to Thunder using the Ingest API: 
curl -X POST https://api.usethunder.com/v1/ingest \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "How do I reset my password?",
        "userId": "user_123"
      },
      {
        "role": "assistant",
        "content": "You can reset your password by clicking the Forgot Password link on the login page.",
        "userId": "assistant"
      }
    ]
  }'
The response includes the instanceId and sessionId that were created (or used if you provided them). Store these IDs on your end - you’ll need them for future ingestion requests to the same session and for querying metrics.

​
Step 3: Add More Messages to the Session

To continue an existing conversation, include the sessionId from the previous response: 
curl -X POST https://api.usethunder.com/v1/ingest \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "sessionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "messages": [
      {
        "role": "user",
        "content": "Thanks, that worked!",
        "userId": "user_123"
      }
    ]
  }'

​
Step 4: Query Your Metrics

Once Thunder has processed your conversations, you can query metrics: 
curl "https://api.usethunder.com/v1/query?groupBy=TOPIC&instanceId=550e8400-e29b-41d4-a716-446655440000&dateRange.start=2024-01-01T00:00:00Z&dateRange.end=2024-01-31T23:59:59Z&timeGranularity=DAY&fields=sessions,users,messages" \
  -H "x-api-key: YOUR_API_KEY"

​
Next Steps

Gaps

Find unanswered questions and missing capabilities

Topics

See what users are talking about

Querying Metrics

Learn query patterns and filters

API Overview

Understand API conventions