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 number (1-based). Must be greater than or equal to 1.
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 "https://api.kortix.ai/threads?page=1&limit=50" \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
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" )
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 Array of thread objects Show Thread Object Fields
Unique identifier for the thread
The project this thread belongs to
Thread name (defaults to “New Chat”)
Thread metadata (custom key-value pairs)
Whether the thread is publicly accessible
ISO 8601 timestamp of creation
ISO 8601 timestamp of last update
Associated project information Project unique identifier
Whether the project is public
ISO 8601 timestamp of project creation
ISO 8601 timestamp of project update
Sandbox configuration if available Sandbox authentication password
project.sandbox.vnc_preview
VNC preview URL
project.sandbox.sandbox_url
Web preview URL
Sandbox authentication token
Pagination metadata Current page number (1-based)
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 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" } ] }
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/workspace/source/backend/core/threads/repo.py:16