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

# Quickstart

> Start tracking events with Turret in under 5 minutes

## Get Your API Key

Before you can start tracking events, you'll need to get your API key from the Turret dashboard.

### Create an Account

<AccordionGroup>
  <Accordion icon="user-plus" title="Sign up for Turret">
    Visit the [Turret Dashboard](https://dashboard.useturret.com) and create your account. You'll get a free tier to start experimenting with event tracking.
  </Accordion>

  <Accordion icon="key" title="Get your API key">
    Once logged in, you'll find your API key in the Dashboard. This key will be used to authenticate your requests to the Turret API.

    <Warning>
      Keep your API key secure and never expose it in client-side code. Use it only in your backend services.
    </Warning>
  </Accordion>
</AccordionGroup>

### Track Your First Event

<AccordionGroup>
  <Accordion icon="code" title="Make your first API call">
    Use the `/track` endpoint to send your first event. At minimum, you only need an event name and metadata:

    ```bash theme={null}
    curl -X POST https://api.useturret.com/track \
      -H "X-API-Key: your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "user_message",
        "metadata": {
          "prompt": "How do I reset my password?"
        }
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_id": "6fa459ea-ee8a-3ca4-894e-db77e160355e"
    }
    ```

    **Important:** Store these IDs and include them in subsequent requests to maintain session continuity for journey tracking.
  </Accordion>

  <Accordion icon="link" title="Continue the conversation">
    For the second message and beyond, include the IDs from the first response:

    ```bash theme={null}
    curl -X POST https://api.useturret.com/track \
      -H "X-API-Key: your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "user_message",
        "session_id": "6fa459ea-ee8a-3ca4-894e-db77e160355e",
        "user_id": "550e8400-e29b-41d4-a716-446655440000",
        "metadata": {
          "prompt": "Thanks, that worked! How do I change my email?"
        }
      }'
    ```

    This connects both messages into a single conversation journey.
  </Accordion>

  <Accordion icon="chart-line" title="View your data">
    After sending a few events, visit your [dashboard](https://dashboard.useturret.com) to see how Turret has automatically clustered your events based on semantic similarity and track user journeys.
  </Accordion>
</AccordionGroup>

## Integration Examples

Here are some common ways to integrate Turret into your application:

<CardGroup>
  <Card title="JavaScript/Node.js" icon="js" href="/essentials/tracking-events#javascript">
    Track events from your JavaScript application
  </Card>

  <Card title="Python" icon="python" href="/essentials/tracking-events#python">
    Integrate with your Python backend
  </Card>

  <Card title="cURL" icon="terminal" href="/essentials/tracking-events#curl">
    Simple HTTP requests for any language
  </Card>

  <Card title="Best Practices" icon="star" href="/essentials/best-practices">
    Learn how to structure your events for maximum insight
  </Card>
</CardGroup>

## Understanding the Request Fields

| Field        | Required       | Description                                                                                                       |
| ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------- |
| `name`       | Yes            | Event name (e.g., "user\_message", "search\_query"). Used to categorize events.                                   |
| `session_id` | Auto-generated | Your conversation/thread ID. Critical for journey tracking. If not provided, Turret generates one and returns it. |
| `user_id`    | Auto-generated | Your user's ID. Enables cross-session analysis. If not provided, Turret generates one and returns it.             |
| `metadata`   | Yes            | Object containing the data to cluster. The key (e.g., "prompt") becomes the clustering dimension.                 |

<Tip>
  **Already have IDs?** If you have your own conversation ID or user ID, pass them directly - Turret will use your IDs instead of generating new ones. Most developers map their existing conversation/thread ID to `session_id`.
</Tip>

## Next Steps

Now that you've tracked your first event, explore these topics:

1. **[Understanding Topics](/essentials/understanding-topics)** - Learn how Turret groups your events and tracks journeys
2. **[Tracking Events](/essentials/tracking-events)** - Detailed guide on event tracking
3. **[Segmentation](/essentials/segmentation)** - Filter topics by categorical metadata (platform, language, etc.)
4. **[Best Practices](/essentials/best-practices)** - Get the most value from your data
5. **[API Reference](/api-reference/introduction)** - Complete API documentation