List Threads

Retrieve a paginated list of threads for the authenticated user

Overview

Returns all threads owned by the authenticated user with pagination support. Results are ordered by creation date (newest first) and include project and sandbox information.

This endpoint automatically triggers background embedding of unembedded threads for semantic search functionality.

Request

page · integer · default: 1

Page number (1-based). Must be greater than or equal to 1.

limit · integer · default: 100

Number of items per page. Must be between 1 and 1000.

Authentication

Requires a valid JWT token via verify_and_get_user_id_from_jwt.

cURL

curl "https://api.kortix.ai/threads?page=1&limit=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Python SDK

from kortix import Kortix

client = Kortix(api_key="YOUR_API_KEY")

response = client.threads.list(
    page=1,
    limit=50
)

for thread in response.threads:
    print(f"{thread.name} - {thread.message_count} messages")

print(f"Total: {response.pagination.total} threads")

JavaScript SDK

import { Kortix } from 'kortix';

const client = new Kortix({
  apiKey: 'YOUR_API_KEY'
});

const response = await client.threads.list({
  page: 1,
  limit: 50
});

response.threads.forEach(thread => {
  console.log(`${thread.name} - ${thread.message_count} messages`);
});

console.log(`Total: ${response.pagination.total} threads`);

Response

threads · array · required

Array of thread objects

Show Thread Object Fields

thread_id · string · required

Unique identifier for the thread

project_id · string

The project this thread belongs to

name · string · required

Thread name (defaults to “New Chat”)

metadata · object · required

Thread metadata (custom key-value pairs)

is_public · boolean · required

Whether the thread is publicly accessible

created_at · string · required

ISO 8601 timestamp of creation

updated_at · string · required

ISO 8601 timestamp of last update

project · object

Associated project information

project.project_id · string · required

Project unique identifier

project.name · string · required

Project name

project.icon_name · string

Icon identifier

project.is_public · boolean · required

Whether the project is public

project.created_at · string · required

ISO 8601 timestamp of project creation

project.updated_at · string · required

ISO 8601 timestamp of project update

project.sandbox · object

Sandbox configuration if available

project.sandbox.id · string

Sandbox external ID

project.sandbox.pass · string

Sandbox authentication password

project.sandbox.vnc_preview · string

VNC preview URL

project.sandbox.sandbox_url · string

Web preview URL

project.sandbox.token · string

Sandbox authentication token

pagination · object · required

Pagination metadata

Show Pagination Fields

page · integer · required

Current page number (1-based)

limit · integer · required

Items per page

total · integer · required

Total number of threads

pages · integer · required

Total number of pages

Response Example

{
  "threads": [
    {
      "thread_id": "550e8400-e29b-41d4-a716-446655440000",
      "project_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Data Analysis",
      "metadata": {},
      "is_public": false,
      "created_at": "2026-03-02T14:30:00Z",
      "updated_at": "2026-03-02T15:45:00Z",
      "project": {
        "project_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "name": "Analytics Project",
        "icon_name": "chart",
        "is_public": false,
        "created_at": "2026-03-02T14:30:00Z",
        "updated_at": "2026-03-02T14:30:00Z",
        "sandbox": {
          "id": "sandbox_abc123",
          "pass": "550e8400-e29b-41d4-a716-446655440001",
          "vnc_preview": "https://sandbox.kortix.ai/vnc/abc123",
          "sandbox_url": "https://sandbox.kortix.ai/web/abc123",
          "token": "tok_xyz789"
        }
      }
    },
    {
      "thread_id": "660e8400-e29b-41d4-a716-446655440001",
      "project_id": "8c9e6679-7425-40de-944b-e07fc1f90ae8",
      "name": "New Chat",
      "metadata": {},
      "is_public": false,
      "created_at": "2026-03-01T10:15:00Z",
      "updated_at": "2026-03-01T10:15:00Z",
      "project": {
        "project_id": "8c9e6679-7425-40de-944b-e07fc1f90ae8",
        "name": "Quick Test",
        "icon_name": null,
        "is_public": false,
        "created_at": "2026-03-01T10:15:00Z",
        "updated_at": "2026-03-01T10:15:00Z",
        "sandbox": null
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 2,
    "pages": 1
  }
}

Empty Results

When no threads are found:

{
  "threads": [],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 0,
    "pages": 0
  }
}

Background Processing

When threads are returned, a background task is automatically triggered to embed any unembedded threads for semantic search. This is non-blocking and doesn’t affect the response time.

Error Responses

Show 400 - Bad Request

Returned when query parameters are invalid:

{
  "detail": [
    {
      "loc": ["query", "page"],
      "msg": "ensure this value is greater than or equal to 1",
      "type": "value_error.number.not_ge"
    }
  ]
}

Show 401 - Unauthorized

Returned when authentication fails or token is invalid.

Show 500 - Internal Server Error

{
  "detail": "Failed to fetch threads: <error message>"
}

Implementation Details

• Threads are ordered by created_at DESC (newest first)
• The query uses a window function to get total count without a separate query
• Results include project and sandbox information via LEFT JOINs
• Maximum limit is 1000 items per page

Source Reference

Implementation: /workspace/source/backend/core/threads/api.py:96
Repository function: /workspace/source/backend/core/threads/repo.py:16