Skip to main content
GET
/
v1
/
agents
/
{agent_id}
/
threads
List threads
curl --request GET \
  --url https://api.notion.com/v1/agents/{agent_id}/threads \
  --header 'Authorization: Bearer <token>' \
  --header 'Notion-Version: <notion-version>'
{
  "object": "<string>",
  "type": "<string>",
  "results": [
    {
      "object": "<string>",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "title": "<string>",
      "status": "pending",
      "created_time": "2023-11-07T05:31:56Z",
      "last_edited_time": "2023-11-07T05:31:56Z",
      "created_by": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "type": "<string>"
      },
      "agent_version": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "number": 123,
        "published_at": "<string>"
      },
      "error": "<string>"
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}
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 integrations.
Results are limited to threads created by the calling integration 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 33333333-3333-3333-3333-333333333333 for the personal agent (Notion AI).

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,
completed,
failed
​
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