> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Widget Threads

> Retrieves all conversation threads for a specific widget. Returns threads ordered by creation date (newest first) with associated messages ordered chronologically.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Path Parameters

**id** `string` *required*

UUID of the widget to retrieve threads for.

### Query Parameters

**page** `number` (default: 1)

Page number for pagination (minimum 1).

**limit** `number` (default: 20)

Number of threads per page (minimum 1, maximum 100).

**thread\_id** `string`

Filter results to a specific thread by its UUID.

### Response

**status** `number`

HTTP status code (200 for success).

**data** `object`

* `threads` (array): Array of thread objects, each containing:
  * `id` (string): Thread UUID
  * `created_at` (string): ISO timestamp
  * `ended_at` (string | null): ISO timestamp of when the thread ended
  * `live_agent_handoff_at` (string | null): ISO timestamp of when the thread was handed off to a live agent
  * `visitor_id` (string | null): UUID of visitor (if available)
  * `messages` (array): Array of message objects, each containing:
    * `id` (string): Message UUID
    * `sender_type` (string): Either "USER" or "ASSISTANT"
    * `created_at` (string): ISO timestamp
    * `content` (string): Message content
    * `original_content` (string | null): Original message content before any modifications
* `total` (number): Total number of threads matching the query (useful for calculating total pages)

> [!NOTE]
>
> This endpoint does not return 404 if no threads exist; it returns an empty array instead.

```json Response theme={null}
{
  "status": 200,
  "data": {
    "threads": [
      {
        "id": "thread_550e8400-e29b-41d4-a716-446655440000",
        "created_at": "2024-01-15T14:30:00Z",
        "ended_at": null,
        "live_agent_handoff_at": null,
        "visitor_id": "visitor_123456789",
        "messages": [
          {
            "id": "msg_001",
            "sender_type": "USER",
            "created_at": "2024-01-15T14:30:00Z",
            "content": "Hello, I need help with my order",
            "original_content": null
          },
          {
            "id": "msg_002",
            "sender_type": "ASSISTANT",
            "created_at": "2024-01-15T14:30:15Z",
            "content": "I'd be happy to help you with your order! Can you please provide your order number?",
            "original_content": null
          },
          {
            "id": "msg_003",
            "sender_type": "USER",
            "created_at": "2024-01-15T14:30:45Z",
            "content": "It's order #12345",
            "original_content": null
          }
        ]
      },
      {
        "id": "thread_660f9511-f3ac-52e5-b827-557766551111",
        "created_at": "2024-01-15T13:15:00Z",
        "ended_at": "2024-01-15T13:20:00Z",
        "live_agent_handoff_at": null,
        "visitor_id": null,
        "messages": [
          {
            "id": "msg_101",
            "sender_type": "USER",
            "created_at": "2024-01-15T13:15:00Z",
            "content": "What are your business hours?",
            "original_content": null
          },
          {
            "id": "msg_102",
            "sender_type": "ASSISTANT",
            "created_at": "2024-01-15T13:15:05Z",
            "content": "Our business hours are Monday through Friday, 9 AM to 6 PM EST.",
            "original_content": null
          }
        ]
      }
    ],
    "total": 2
  },
  "errors": null
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.