Skip to main content
GET
/
v1
/
comments
TypeScript SDK
import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.comments.list({
  block_id: "b55c9c91-384d-452b-81db-d1ef79372b75",
  start_cursor: undefined,
  page_size: 50
})
{
  "object": "<string>",
  "next_cursor": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "has_more": true,
  "results": [
    {
      "object": "<string>",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "parent": {
        "type": "<string>",
        "page_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      },
      "discussion_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created_time": "2023-12-25",
      "last_edited_time": "2023-12-25",
      "created_by": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "object": "<string>"
      },
      "rich_text": [
        {
          "plain_text": "<string>",
          "href": "<string>",
          "annotations": {
            "bold": true,
            "italic": true,
            "strikethrough": true,
            "underline": true,
            "code": true,
            "color": "default"
          },
          "type": "<string>",
          "text": {
            "content": "<string>",
            "link": {
              "url": "<string>"
            }
          }
        }
      ],
      "display_name": {
        "type": "custom",
        "resolved_name": "<string>"
      },
      "attachments": [
        {
          "category": "audio",
          "file": {
            "url": "<string>",
            "expiry_time": "2023-12-25"
          }
        }
      ]
    }
  ],
  "type": "<string>",
  "comment": {}
}
See Pagination for details about how to use a cursor to iterate through the list.

​
Errors

Each Public API endpoint can return several possible error codes. See the Error codes section of the Status codes documentation for more information.
Reminder: Turn on integration comment capabilitiesIntegration capabilities for reading and inserting comments are off by default.This endpoint requires an integration to have read comment capabilities. Attempting to call this endpoint without read comment capabilities will return an HTTP response with a 403 status code.For more information on integration capabilities, see the capabilities guide. To update your integration settings, visit the integration dashboard.

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 2025-09-03.

Available options:
2025-09-03

Query Parameters

​
block_id
string
required

Identifier for a Notion block or page.

​
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"
​
next_cursor
string<uuid> | null
required
​
has_more
boolean
required
​
results
object[]
required
​
type
string
required

Always comment

Allowed value: "comment"
​
comment
object
required