Skip to main content
GET
List threads
This is an internal/undocumented endpoint. It is not part of the public API and may change without notice. Do not rely on this endpoint for production connections.
Results are limited to threads created by the calling connection for the specified agent. Each thread object includes a status field that is one of pending, completed, or failed. When a thread’s status is failed, the response includes an error field containing a human-readable message describing the failure reason. The error field is omitted for threads that are not in a failed state.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Notion-Version
enum<string>
required

The API version to use for this request. The latest version is 2026-03-11.

Available options:
2026-03-11

Path Parameters

agent_id
required

The ID of the agent. Use a UUID for custom agents or notion_ai for Notion Agent (personal agent); the reserved UUID 33333333-3333-3333-3333-333333333333 remains supported for backward compatibility.

Query Parameters

id
string

Filter threads by ID (exact match).

title
string

Filter threads by title (case-insensitive substring match).

status
enum<string>

Filter threads by status.

Available options:
pending,
requires_action,
completed,
failed
activity
enum<string>

Filter threads by agent activity state. Defaults to all.

Available options:
all,
pending,
in_progress,
failed,
success
created_by
string[]

Filter threads by one or more creator IDs. Use "me" for the API bot and user associated with the API token.

Required array length: 1 - 100 elements
last_used_by
string[]

Filter threads by one or more IDs of actors who last used them. Use "me" for the API bot and user associated with the API token.

Required array length: 1 - 100 elements
sort_by
enum<string>

Timestamp used to sort threads. Defaults to created_time.

Available options:
created_time,
last_used_time
sort_direction
enum<string>

Sort direction. Defaults to descending.

Available options:
ascending,
descending
start_cursor
string

If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results.

page_size
integer

The number of items from the full list desired in the response. Maximum: 100

Required range: 1 <= x <= 100

Response

object
string
required

Always list

Allowed value: "list"
type
string
required

Always thread

Allowed value: "thread"
results
object[]
required
Maximum array length: 100
has_more
boolean
required
next_cursor
string | null
required