Introduction

Welcome to the Turret API

Turret is a product analytics API designed for AI/LLM applications. It provides:

Semantic Topic Clustering: Automatically groups similar user messages/prompts by meaning using embeddings
User Journey Tracking: Tracks how users flow through different topics within conversations

Single Endpoint Design

One endpoint to track all your events - simple and powerful

Authentication

All API requests must include your project API key in the X-API-Key header:

curl -X POST https://api.useturret.com/track \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json"

Never expose your API key in client-side code. Always make API calls from your backend services.

Base URL

All API requests should be made to:

https://api.useturret.com

Request Format

All requests must:

Use HTTPS
Include Content-Type: application/json header
Include X-API-Key header with your project API key
Send data as JSON in the request body

Basic Request Example

{
  "name": "user_prompt",
  "session_id": "conv_abc123",
  "user_id": "user_456",
  "metadata": {
    "prompt": "How do I reset my password?"
  }
}

Field Reference

Field	Required	Description
`name`	Yes	Event name (e.g., “user_prompt”, “search_query”). Used to categorize events.
`session_id`	Recommended	Your conversation/thread ID. Critical for journey tracking. Events with the same session_id are connected into a user flow.
`user_id`	Optional	Your user’s ID. Enables cross-session analysis.
`metadata`	Yes	Object containing the data to cluster. The key (e.g., “prompt”) becomes the clustering dimension.

Response Format

All responses are returned as JSON with the following structure:

Success Response

{
  "success": true,
  "message": "Event tracked successfully",
  "event_id": "evt_1234567890"
}

Error Response

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

Rate Limits

Turret implements rate limiting to ensure service quality:

Free trial: 250k total events (within 14 days)
Pro plan: 1,000,000 events per month
Business plan: 10,000,000 events per month
Enterprise: Custom limits

When you exceed your rate limit, you’ll receive a 429 Too Many Requests response with details about when you can retry.

Error Codes

Common error codes you might encounter:

Code	Description
`INVALID_API_KEY`	The provided API key is invalid or missing
`RATE_LIMIT_EXCEEDED`	You have exceeded your event limit
`INVALID_REQUEST`	The request format is incorrect
`MISSING_REQUIRED_FIELD`	Required fields are missing from the request
`TEXT_TOO_LONG`	Metadata text exceeds maximum length

Metadata Field Types

Turret automatically detects and classifies your metadata fields:

Type	Description	Dashboard Feature
text	Free-form text content	Semantic clustering into topics
enum	Categorical values	Segmentation and filtering
number	Numeric values	Aggregation

Field types are detected on first event and re-validated as more data arrives. You can override detected types in the dashboard Settings → Metadata tab.

Getting Started

Get your API key from the Turret Dashboard
Make your first request to /track with event data
View your results in the dashboard to see automatic clustering and journeys

Track Your First Event

Learn how to send events to Turret

API Documentation

Endpoints

Welcome to the Turret API

Single Endpoint Design

Authentication

Base URL

Request Format

Basic Request Example

Field Reference

Response Format

Success Response

Error Response

Rate Limits

Error Codes

Metadata Field Types

Getting Started

Track Your First Event

​Welcome to the Turret API

Single Endpoint Design

​Authentication

​Base URL

​Request Format

​Basic Request Example

​Field Reference

​Response Format

​Success Response

​Error Response

​Rate Limits

​Error Codes

​Metadata Field Types

​Getting Started

Track Your First Event

Welcome to the Turret API

Authentication

Base URL

Request Format

Basic Request Example

Field Reference

Response Format

Success Response

Error Response

Rate Limits

Error Codes

Metadata Field Types

Getting Started