> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usethunder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instances

> Organize analytics by product, deployment, or tenant

## 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

<CardGroup cols={2}>
  <Card title="Multiple Products" icon="boxes-stacked">
    If you have separate AI products (support bot, sales assistant, etc.) - each product gets its own instance.
  </Card>

  <Card title="Environment Separation" icon="code-branch">
    Keep production and staging analytics separate by using different instances.
  </Card>
</CardGroup>

## 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:

```bash theme={null}
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.

<Warning>
  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.
</Warning>

## Querying by Instance

All query requests require an `instanceId`:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Don't over-segment">
    More instances means more fragmented data. Only create separate instances when you genuinely need isolated analytics.
  </Accordion>
</AccordionGroup>