Skip to main content

​
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

FieldRequiredDescription
nameYesEvent name (e.g., “user_prompt”, “search_query”). Used to categorize events.
session_idRecommendedYour conversation/thread ID. Critical for journey tracking. Events with the same session_id are connected into a user flow.
user_idOptionalYour user’s ID. Enables cross-session analysis.
metadataYesObject 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:
CodeDescription
INVALID_API_KEYThe provided API key is invalid or missing
RATE_LIMIT_EXCEEDEDYou have exceeded your event limit
INVALID_REQUESTThe request format is incorrect
MISSING_REQUIRED_FIELDRequired fields are missing from the request
TEXT_TOO_LONGMetadata text exceeds maximum length

​
Metadata Field Types

Turret automatically detects and classifies your metadata fields:
TypeDescriptionDashboard Feature
textFree-form text contentSemantic clustering into topics
enumCategorical valuesSegmentation and filtering
numberNumeric valuesAggregation
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

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

Track Your First Event

Learn how to send events to Turret