Skip to main content
GET
/
v1
/
widget
/
{id}
/
threads
Get Widget Threads
curl --request GET \
  --url https://api.bland.ai/v1/widget/{id}/threads \
  --header 'authorization: <authorization>'
{
  "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
}

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.

​
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)
This endpoint does not return 404 if no threads exist; it returns an empty array instead.
{
  "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