Skip to content
/
Thread object
Last updated

Thread object

🔨 In Development — This section is still being developed and may change.
The Thread object represents a conversation thread with messages, metadata, and configuration settings.

Properties

id string required

The unique identifier for the thread. Always starts with thread_.

object string required

The object type, which is always thread.

createdAt integer required

Unix timestamp (in seconds) of when the thread was created.

updatedAt integer required

Unix timestamp (in seconds) of when the thread was last updated.

metadata object optional

Custom key-value pairs for attaching structured information to the thread. Maximum 16 key-value pairs. Keys must be ≤64 characters, values ≤512 characters.

assistantId string optional

ID of the assistant bound to this thread. When provided, the assistant's configuration is applied to all responses in this thread.

organizationId string required

The unique identifier of the organization that owns this thread. Used for billing, access control, and resource management. All API requests must be scoped to an organization.

userId string required

The unique identifier of the user who created this thread.

title string optional

Display name for the thread. Maximum 200 characters. Can be set manually or generated using the Generate AI Name endpoint.

visibleInUi boolean optional · Defaults to true

Whether this thread should be visible in the user interface. Requires Bearer token authentication to modify.

messageCount integer required

The total number of messages in this thread. Updated automatically when messages are added or removed.

status string optional · Defaults to inactive

The current streaming status of the thread. Can be streaming or inactive.

{
  "id": "thread_abc123",
  "object": "thread",
  "createdAt": 1741476542,
  "updatedAt": 1741476600,
  "metadata": {},
  "assistantId": null,
  "organizationId": "ORG_123",
  "userId": "uid_user123",
  "title": "General Question",
  "visibleInUi": true,
  "messageCount": 0,
  "status": "inactive"
}

Thread States

Threads can exist in different states that affect their behavior:

Open (Default)

  • Accepts new messages
  • Visible in UI (if visibleInUi is true)
  • Can be modified and updated

Locked

  • Read-only, no new messages can be added
  • Still visible in UI
  • Metadata can still be updated

Archived

  • Preserved but inactive
  • Hidden from UI by default
  • Cannot be modified

Metadata Guidelines

The metadata field supports custom key-value pairs for organizing and categorizing threads:

Common Metadata Keys

  • category - Thread category (e.g., "support", "sales", "technical")
  • priority - Priority level (e.g., "low", "medium", "high", "urgent")
  • status - Current status (e.g., "open", "in_progress", "resolved", "closed")
  • tags - Array of tags for categorization
  • source - Origin of the thread (e.g., "web", "api", "mobile")
  • department - Department handling the thread

Best Practices

  • Use consistent key names across your organization
  • Keep values concise and meaningful
  • Use arrays for multiple values (e.g., tags)
  • Avoid storing sensitive information in metadata
Previous page
Next page