🌍 Global Mirror — Visit original CN site →
Skip to main content
POST
/
threads
/
search
Search Threads
curl --request POST \
  --url https://api.example.com/threads/search \
  --header 'Content-Type: application/json' \
  --data '
{
  "ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "metadata": {},
  "values": {},
  "status": "idle",
  "limit": 10,
  "offset": 0,
  "sort_by": "thread_id",
  "sort_order": "asc",
  "select": [
    "thread_id"
  ],
  "extract": {}
}
'
[
  {
    "thread_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "metadata": {},
    "status": "idle",
    "state_updated_at": "2023-11-07T05:31:56Z",
    "config": {},
    "values": {},
    "interrupts": {},
    "ttl": {
      "strategy": "delete",
      "ttl_minutes": 123,
      "expires_at": "2023-11-07T05:31:56Z"
    },
    "extracted": {}
  }
]

Body

application/json

Payload for listing threads.

​
ids
string<uuid>[]

List of thread IDs to include. Others are excluded.

​
metadata
Metadata · object

Thread metadata to filter on.

​
values
Values · object

State values to filter on.

​
status
enum<string>

Thread status to filter on.

Available options:
idle,
busy,
interrupted,
error
​
limit
integer
default:10

Maximum number to return.

Required range: 1 <= x <= 1000
​
offset
integer
default:0

Offset to start from.

Required range: x >= 0
​
sort_by
enum<string>

Sort by field.

Available options:
thread_id,
status,
created_at,
updated_at,
state_updated_at
​
sort_order
enum<string>

Sort order.

Available options:
asc,
desc
​
select
enum<string>[]

Specify which fields to return. If not provided, all fields are returned.

Available options:
thread_id,
created_at,
updated_at,
state_updated_at,
metadata,
config,
status,
values,
interrupts
​
extract
Extract · object

Map of alias to JSONB path for extracting specific values. Paths must start with values, metadata, config, or interrupts. Example: {"last_msg": "values.messages[-1]"}.

Response

Success

​
thread_id
string<uuid>
required

The ID of the thread.

​
created_at
string<date-time>
required

The time the thread was created.

​
updated_at
string<date-time>
required

The last time the thread was updated.

​
metadata
Metadata · object
required

The thread metadata.

​
status
enum<string>
required

The status of the thread.

Available options:
idle,
busy,
interrupted,
error
​
state_updated_at
string<date-time>

The last time the thread state was updated.

​
config
Config · object

The thread config.

​
values
Values · object

The current state of the thread.

​
interrupts
Interrupts · object

The current interrupts of the thread.

​
ttl
TTL Info · object

TTL information if set for this thread. Only present when ?include=ttl is passed.

​
extracted
Extracted · object

Extracted values from thread JSONB columns, populated when extract is specified in search request.