Skip to main content
The Threads API allows you to organize related LLM requests into conversations, making it easier to track multi-turn interactions and maintain context across multiple API calls.

​
Overview

Threads provide a way to:
  • Group related requests together
  • Track conversation history
  • Filter traces by conversation
  • Analyze user journeys and agent workflows

​
List threads

Retrieve all threads with optional filtering.

​
Endpoint

GET /api/threads
POST /api/threads (with filters in body)

​
Parameters

​
limit
integer
default:"100"
Maximum number of threads to return
​
offset
integer
default:"0"
Number of threads to skip for pagination
​
project_id
string
Filter threads by project ID

​
Response

​
threads
array
Array of thread objects

​
Example

cURL
curl http://localhost:9090/api/threads \
  -H "Content-Type: application/json"
Python
import requests

response = requests.get('http://localhost:9090/api/threads')
threads = response.json()

for thread in threads['threads']:
    print(f"Thread {thread['id']}: {thread['run_count']} runs")

​
Get thread details

Retrieve detailed information about a specific thread.

​
Endpoint

GET /api/threads/{id}

​
Path Parameters

​
id
string
required
Thread ID

​
Response

​
id
string
Thread identifier
​
created_at
string
Thread creation timestamp
​
updated_at
string
Last update timestamp
​
metadata
object
Custom metadata
​
runs
array
Array of run objects in this thread

​
Example

cURL
curl http://localhost:9090/api/threads/thread_abc123

​
Update thread

Update thread metadata or properties.

​
Endpoint

PUT /api/threads/{id}

​
Path Parameters

​
id
string
required
Thread ID to update

​
Request Body

​
metadata
object
Custom metadata to attach to the thread

​
Example

cURL
curl -X PUT http://localhost:9090/api/threads/thread_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "user_id": "user_123",
      "conversation_type": "support",
      "resolved": true
    }
  }'

​
Using threads in requests

Assign requests to threads using the X-Thread-ID header: 
curl http://localhost:9090/v1/chat/completions \
  -H "X-Thread-ID: conversation-123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'
All requests with the same thread ID will be grouped together in the UI and API.

​
Filtering traces by thread

Use thread IDs to filter traces: 
curl "http://localhost:9090/api/traces?thread_id=conversation-123"
This returns all traces belonging to the specified thread.

​
Best practices

Choose descriptive thread IDs that help identify conversations:
  • user-123-support for support conversations
  • session-abc-onboarding for onboarding flows
  • agent-xyz-task-456 for agent workflows
Attach relevant metadata to threads as soon as they’re created. This makes filtering and analysis easier later.
Threads are created automatically when you first use a thread ID in a request. You don’t need to explicitly create them.
Regularly archive or delete old threads to keep your database manageable. There’s no automatic cleanup.

​
Next steps

Traces API

Query traces within threads

Runs API

View run details in threads

Real-time Tracing

Monitor thread activity in real-time

Projects

Organize threads by project

Build docs developers (and LLMs) love

Get started for freeTalk to us