Instances

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:

From the dashboard - Create and manage instances through the Thunder dashboard
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:

Data	Description
Topics	Topic detection learns from each instance’s conversations
Signals	Satisfaction signals are tracked per instance
Gaps	Knowledge and tool gaps are detected per instance
Users	End user tracking is scoped to each instance
Sessions	All 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

Plan your instance structure early

Decide how you want to segment analytics before you start ingesting data. Changing instance structure later requires re-ingesting historical data.

Use meaningful instance IDs

While Thunder accepts any UUID, use IDs that map to entities in your system (clone IDs, product IDs) for easier correlation.

Don't over-segment

More instances means more fragmented data. Only create separate instances when you genuinely need isolated analytics.

Getting Started

Fundamentals

Features

Guides

Security

What is an Instance?

When to Use Multiple Instances

Multiple Products

Environment Separation

Single Instance

Creating Instances

Querying by Instance

Instance Isolation

Best Practices

​What is an Instance?

​When to Use Multiple Instances

Multiple Products

Environment Separation

​Single Instance

​Creating Instances

​Querying by Instance

​Instance Isolation

​Best Practices

What is an Instance?

When to Use Multiple Instances

Single Instance

Creating Instances

Querying by Instance

Instance Isolation

Best Practices