Skip to content
/
Thread object
Last updated

Thread object

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.

created_at string required

ISO 8601 timestamp of when the thread was created. Example: 2025-11-17T10:00:00Z

last_message_at string optional

ISO 8601 timestamp of when the last message was added to the thread. Example: 2025-11-17T10:05:00Z

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.

assistant_id string optional

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

organization_id 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.

user_id string required

The unique identifier of the user who created this thread. Always starts with usr_.

title string optional

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

visible_in_ui boolean optional · Defaults to true

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

message_count integer required

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

status string required

The current status of the thread. Always active for non-deleted threads.

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