Overview Retrieves comprehensive details about a thread, including project information, sandbox configuration, message count, and recent agent runs.
This endpoint supports both authenticated and unauthenticated access. Public threads can be accessed without authentication.
Request The unique identifier of the thread to retrieve
Authentication Optional JWT token. If provided, validates user access to private threads.
curl https://api.kortix.ai/threads/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
from kortix import Kortix client = Kortix( api_key = "YOUR_API_KEY" ) thread = client.threads.get( thread_id = "550e8400-e29b-41d4-a716-446655440000" ) print ( f "Thread: { thread.name } " ) print ( f "Messages: { thread.message_count } " )
import { Kortix } from 'kortix' ; const client = new Kortix ({ apiKey: 'YOUR_API_KEY' }); const thread = await client . threads . get ({ threadId: '550e8400-e29b-41d4-a716-446655440000' }); console . log ( `Thread: ${ thread . name } ` ); console . log ( `Messages: ${ thread . message_count } ` );
Response The unique identifier of the thread
The project this thread belongs to
The name of the thread (defaults to “New Chat”)
Additional thread metadata (custom key-value pairs)
Whether the thread is publicly accessible
ISO 8601 timestamp of thread creation
ISO 8601 timestamp of last update
Associated project details Show Project Object Fields
The project’s unique identifier
Whether the project is publicly accessible
Icon identifier for the project
ISO 8601 timestamp of project creation
ISO 8601 timestamp of last project update
Sandbox configuration and access details Authentication password for sandbox access
project.sandbox.vnc_preview
VNC preview URL for remote desktop access
project.sandbox.sandbox_url
Web preview URL (typically port 8080)
Authentication token for sandbox access
Total number of messages in the thread
List of recent agent execution runs Show Agent Run Object Fields
Agent run unique identifier
Current status: running, completed, failed, etc.
ISO 8601 timestamp when the run started
ISO 8601 timestamp when the run completed (null if still running)
Only present for threads in pending state (optimistic creation)
Response Example { "thread_id" : "550e8400-e29b-41d4-a716-446655440000" , "project_id" : "7c9e6679-7425-40de-944b-e07fc1f90ae7" , "name" : "Data Analysis Project" , "metadata" : { "title" : "Data Analysis Project" }, "is_public" : false , "created_at" : "2026-03-02T10:30:00Z" , "updated_at" : "2026-03-02T14:25:00Z" , "project" : { "project_id" : "7c9e6679-7425-40de-944b-e07fc1f90ae7" , "name" : "My Project" , "description" : "" , "is_public" : false , "icon_name" : "code" , "created_at" : "2026-03-02T10:30:00Z" , "updated_at" : "2026-03-02T10: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" } }, "message_count" : 42 , "recent_agent_runs" : [ { "id" : "run_123" , "status" : "completed" , "started_at" : "2026-03-02T14:20:00Z" , "completed_at" : "2026-03-02T14:25:00Z" } ] }
Special Behaviors Pending Threads If a thread was just created using optimistic creation and hasn’t been persisted to the database yet, the endpoint returns a minimal response with _pending: true:
{ "thread_id" : "550e8400-e29b-41d4-a716-446655440000" , "project_id" : "7c9e6679-7425-40de-944b-e07fc1f90ae7" , "name" : "New Chat" , "metadata" : {}, "is_public" : false , "created_at" : "2026-03-02T15:00:00Z" , "updated_at" : "2026-03-02T15:00:00Z" , "project" : { "project_id" : "7c9e6679-7425-40de-944b-e07fc1f90ae7" , "name" : "New Project" , "description" : "" , "sandbox" : {}, "is_public" : false , "icon_name" : null , "created_at" : "2026-03-02T15:00:00Z" , "updated_at" : "2026-03-02T15:00:00Z" }, "message_count" : 0 , "recent_agent_runs" : [], "_pending" : true }
Automatic Sandbox Startup When retrieving a thread with an existing sandbox, the sandbox is automatically started in the background (non-blocking) to ensure it’s ready for use.
Error Responses { "detail" : "Thread not found" }
The thread doesn’t exist or is not available in the pending cache. Returned when the authenticated user doesn’t have access to a private thread.
Show 500 - Internal Server Error
{ "detail" : "Failed to fetch thread: <error message>" }
Source Reference Implementation: /workspace/source/backend/core/threads/api.py:411