Skip to main content

​
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

Visit the Turret Dashboard and create your account. You’ll get a free tier to start experimenting with event tracking.
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.
Keep your API key secure and never expose it in client-side code. Use it only in your backend services.

​
Track Your First Event

Use the /track endpoint to send your first event. At minimum, you only need an event name and metadata:
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:
{
  "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.
For the second message and beyond, include the IDs from the first response:
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.
After sending a few events, visit your dashboard to see how Turret has automatically clustered your events based on semantic similarity and track user journeys.

​
Integration Examples

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

JavaScript/Node.js

Track events from your JavaScript application

Python

Integrate with your Python backend

cURL

Simple HTTP requests for any language

Best Practices

Learn how to structure your events for maximum insight

​
Understanding the Request Fields

FieldRequiredDescription
nameYesEvent name (e.g., “user_message”, “search_query”). Used to categorize events.
session_idAuto-generatedYour conversation/thread ID. Critical for journey tracking. If not provided, Turret generates one and returns it.
user_idAuto-generatedYour user’s ID. Enables cross-session analysis. If not provided, Turret generates one and returns it.
metadataYesObject containing the data to cluster. The key (e.g., “prompt”) becomes the clustering dimension.
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.

​
Next Steps

Now that you’ve tracked your first event, explore these topics:
  1. Understanding Topics - Learn how Turret groups your events and tracks journeys
  2. Tracking Events - Detailed guide on event tracking
  3. Segmentation - Filter topics by categorical metadata (platform, language, etc.)
  4. Best Practices - Get the most value from your data
  5. API Reference - Complete API documentation