Skip to main content

​
What is an Instance?

An instance represents a distinct product, deployment, or tenant within your AI application. All analytics in Thunder are scoped to instances - topics, signals, gaps, and metrics are tracked separately for each instance.

​
When to Use Multiple Instances

Multiple Products

If you have separate AI products (support bot, sales assistant, etc.) - each product gets its own instance.

Environment Separation

Keep production and staging analytics separate by using different instances.

​
Single Instance

If you have one AI product with one deployment, you can use a single instance. Thunder creates a default instance for you when you first ingest data without specifying an instanceId.

​
Creating Instances

Instances can be created in two ways:
  1. From the dashboard - Create and manage instances through the Thunder dashboard
  2. Automatically on first ingest - If you don’t pass an instanceId, 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 '{
    "messages": [...]
  }'
The response includes the instanceId that was created - store this to use for future requests.
If you pass an instanceId that doesn’t exist, the request will fail. Always use an instance ID from the dashboard or from a previous ingest response.

​
Querying by Instance

All query requests require an instanceId: 
curl "https://api.usethunder.com/v1/query?\
groupBy=TOPIC&\
instanceId=clone-alice-uuid&\
dateRange.start=2024-01-01T00:00:00Z&\
dateRange.end=2024-01-31T23:59:59Z&\
timeGranularity=ALL&\
fields=sessions,messages" \
  -H "x-api-key: YOUR_API_KEY"

​
Instance Isolation

Each instance has completely separate:
DataDescription
TopicsTopic detection learns from each instance’s conversations
SignalsSatisfaction signals are tracked per instance
GapsKnowledge and tool gaps are detected per instance
UsersEnd user tracking is scoped to each instance
SessionsAll sessions belong to exactly one instance
This means if “Alice Clone” and “Bob Clone” both get asked about pricing, they’ll each have their own “Pricing” topic with separate metrics.

​
Best Practices

Decide how you want to segment analytics before you start ingesting data. Changing instance structure later requires re-ingesting historical data.
While Thunder accepts any UUID, use IDs that map to entities in your system (clone IDs, product IDs) for easier correlation.
More instances means more fragmented data. Only create separate instances when you genuinely need isolated analytics.