# Thread object

div
strong
🔨 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](/docs/api-reference/threads/generate-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`.

Basic Thread

```json
{
  "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 with Assistant

```json
{
  "id": "thread_xyz789",
  "object": "thread",
  "createdAt": 1741476000,
  "updatedAt": 1741476100,
  "metadata": {
    "category": "support",
    "priority": "high",
    "tags": ["billing", "urgent"]
  },
  "assistantId": "asst_support_agent",
  "organizationId": "ORG_123",
  "userId": "uid_user123",
  "title": "Customer Support Query",
  "visibleInUi": true,
  "messageCount": 5,
  "status": "inactive"
}
```

Streaming Thread

```json
{
  "id": "thread_streaming_123",
  "object": "thread",
  "createdAt": 1741475000,
  "updatedAt": 1741475200,
  "metadata": {},
  "assistantId": "asst_support_agent",
  "organizationId": "ORG_123",
  "userId": "uid_user123",
  "title": "Live Support",
  "visibleInUi": true,
  "messageCount": 12,
  "status": "streaming"
}
```

## 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


## Related Resources

- [Threads Overview](/docs/documentation/core-concepts/threads-overview)
- [Create Thread](/docs/api-reference/threads/create)
- [List Threads](/docs/api-reference/threads/list)
- [Update Thread](/docs/api-reference/threads/update)
- [Thread Context Modes](/docs/documentation/core-concepts/thread-context-modes)