Get Thread

Retrieve detailed information about a specific thread

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

thread_id · string · required

The unique identifier of the thread to retrieve

Authentication

Optional JWT token. If provided, validates user access to private threads.

cURL

curl https://api.kortix.ai/threads/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Python SDK

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}")

JavaScript SDK

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

thread_id · string · required

The unique identifier of the thread

project_id · string

The project this thread belongs to

name · string · required

The name of the thread (defaults to “New Chat”)

metadata · object · required

Additional thread metadata (custom key-value pairs)

is_public · boolean · required

Whether the thread is publicly accessible

created_at · string · required

ISO 8601 timestamp of thread creation

updated_at · string · required

ISO 8601 timestamp of last update

project · object

Associated project details

Show Project Object Fields

project.project_id · string · required

The project’s unique identifier

project.name · string · required

The project name

project.description · string · required

The project description

project.is_public · boolean · required

Whether the project is publicly accessible

project.icon_name · string

Icon identifier for the project

project.created_at · string · required

ISO 8601 timestamp of project creation

project.updated_at · string · required

ISO 8601 timestamp of last project update

project.sandbox · object · required

Sandbox configuration and access details

project.sandbox.id · string

The sandbox external ID

project.sandbox.pass · string

Authentication password for sandbox access

project.sandbox.vnc_preview · string

VNC preview URL for remote desktop access

project.sandbox.sandbox_url · string

Web preview URL (typically port 8080)

project.sandbox.token · string

Authentication token for sandbox access

message_count · integer · required

Total number of messages in the thread

recent_agent_runs · array · required

List of recent agent execution runs

Show Agent Run Object Fields

id · string · required

Agent run unique identifier

status · string · required

Current status: running, completed, failed, etc.

started_at · string · required

ISO 8601 timestamp when the run started

completed_at · string

ISO 8601 timestamp when the run completed (null if still running)

_pending · boolean

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

Show 404 - Not Found

{
  "detail": "Thread not found"
}

The thread doesn’t exist or is not available in the pending cache.

Show 403 - Forbidden

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