Track Event

Overview

The /track endpoint is the core of Turret’s API. Use it to send user events with metadata for automatic semantic clustering and journey tracking.

Request Body

name

string

required

Event name (e.g., “user_message”, “search_query”). Used to categorize events.

session_id

string

Your conversation/thread ID. Critical for journey tracking. Auto-generated if not provided. Include the returned session_id in subsequent messages to connect them into a conversation.

user_id

string

Your user’s ID. Enables cross-session analysis. Auto-generated if not provided. Store and reuse to track the same user across conversations.

metadata

object

required

Object containing the data to cluster. The key (e.g., “prompt”) becomes the clustering dimension. The value is the text that gets semantically clustered.

Example Request

First Message (IDs Auto-Generated)

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?"
    }
  }'

Subsequent Messages (Include IDs)

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! How do I change my email?"
    }
  }'

Response

session_id

string

The session ID for this event. Either your provided ID or an auto-generated UUID. Store this and include it in subsequent messages to connect them into a conversation journey.

user_id

string

The user ID for this event. Either your provided ID or an auto-generated UUID. Store this to track the same user across conversations.

Example Response

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

Important: Store the returned session_id and include it in all subsequent messages within the same conversation. Without this, Turret cannot track the user’s journey through topics.

How It Works

Event Ingestion: When you POST an event, Turret stores it with its metadata.
Embedding Generation: Turret generates a vector embedding for the metadata value (e.g., the prompt text) using an embedding model.
Semantic Clustering: Events are grouped into clusters based on embedding similarity. Similar prompts end up in the same cluster, even if they use different words:
- “How do I reset my password?” and “I forgot my login credentials” → Same cluster
Cluster Labeling: Clusters are automatically labeled with human-readable descriptions using an LLM (e.g., “Password Reset Requests”).
Journey Tracking: When events share the same session_id, Turret tracks transitions between clusters:
- User asks about pricing (Cluster A)
- User asks about features (Cluster B)
- User asks about pricing again (Cluster A)
- This creates a journey: A → B → A

Common Use Cases

Track User Messages (Minimal)

{
  "name": "user_message",
  "metadata": {
    "prompt": "Write a product description for wireless headphones"
  }
}

Response returns session_id and user_id - store these for subsequent messages.

Track with Your Own IDs

{
  "name": "user_message",
  "session_id": "your-conversation-id",
  "user_id": "your-user-id",
  "metadata": {
    "prompt": "How do I export my data?"
  }
}

Track Search Queries

{
  "name": "search_query",
  "metadata": {
    "query": "best coffee shops near me"
  }
}

Track with Additional Context

{
  "name": "user_message",
  "session_id": "thread_xyz",
  "metadata": {
    "prompt": "How do I export my data?",
    "detected_language": "english",
    "platform": "mobile"
  }
}

Error Responses

Invalid API Key (401)

{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Missing Required Fields (400)

{
  "success": false,
  "error": "Missing required field: name",
  "code": "MISSING_REQUIRED_FIELD"
}

Rate Limit Exceeded (429)

{
  "success": false,
  "error": "Rate limit exceeded. Try again in 1 hour.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 3600
}

Best Practices

Session ID Management

First message: Omit session_id - Turret generates one
Store the response: Save the returned session_id
Subsequent messages: Always include the stored session_id
New conversation: Omit session_id again to start fresh

Using Your Own IDs

If you already have conversation IDs (most apps do):

Pass your conversation ID as session_id
Pass your user ID as user_id
Turret uses your IDs as-is

Event Names

Use descriptive names (e.g., “user_message”, “search_query”)
Keep names consistent across your app
Avoid generic names like “event” or “action”

Metadata Structure

Include the user’s actual text in the prompt or query field
Keep text fields under 10,000 characters
Additional metadata fields provide context but aren’t clustered

Error Handling

Check response status codes
Implement retry logic with exponential backoff
Don’t let tracking failures break your main application flow

Critical for journey tracking: The session_id connects messages into a conversation. Without it, Turret can cluster topics but cannot show how users flow through them.

Authorizations

X-API-Key

string

header

required

Your project API key from the Turret dashboard

Body

application/json

Event data to track

name

string

required

Event name (e.g., 'user_prompt', 'search_query'). Used to categorize events.

Required string length: 1 - 255

Example:

"user_prompt"

metadata

object

required

Object containing the data to cluster. The key (e.g., 'prompt') becomes the clustering dimension. The value is the text that gets semantically clustered.

Example:

{ "prompt": "How do I reset my password?" }

session_id

string

Your conversation/thread ID. Critical for journey tracking. Events with the same session_id are connected into a user flow.

Example:

"conv_abc123"

user_id

string

Your user's ID. Enables cross-session analysis (tracking the same user across multiple conversations).

Example:

"user_456"

Response

Event successfully tracked

success

boolean

Indicates if the event was successfully tracked

Example:

true

message

string

Human-readable message about the result

Example:

"Event tracked successfully"

event_id

string

Unique identifier for the tracked event

Example:

"evt_1234567890abcdef"

API Documentation

Endpoints

Overview

Request Body

Example Request

First Message (IDs Auto-Generated)

Subsequent Messages (Include IDs)

Response

Example Response

How It Works

Common Use Cases

Track User Messages (Minimal)

Track with Your Own IDs

Track Search Queries

Track with Additional Context

Error Responses

Invalid API Key (401)

Missing Required Fields (400)

Rate Limit Exceeded (429)

Best Practices

Session ID Management

Using Your Own IDs

Event Names

Metadata Structure

Error Handling

Authorizations

Body

Response

API Documentation

Endpoints

​Overview

​Request Body

​Example Request

​First Message (IDs Auto-Generated)

​Subsequent Messages (Include IDs)

​Response

​Example Response

​How It Works

​Common Use Cases

​Track User Messages (Minimal)

​Track with Your Own IDs

​Track Search Queries

​Track with Additional Context

​Error Responses

​Invalid API Key (401)

​Missing Required Fields (400)

​Rate Limit Exceeded (429)

​Best Practices

​Session ID Management

​Using Your Own IDs

​Event Names

​Metadata Structure

​Error Handling

Authorizations

Body

Response

Overview

Request Body

Example Request

First Message (IDs Auto-Generated)

Subsequent Messages (Include IDs)

Response

Example Response

How It Works

Common Use Cases

Track User Messages (Minimal)

Track with Your Own IDs

Track Search Queries

Track with Additional Context

Error Responses

Invalid API Key (401)

Missing Required Fields (400)

Rate Limit Exceeded (429)

Best Practices

Session ID Management

Using Your Own IDs

Event Names

Metadata Structure

Error Handling