Skip to content

Notion: List comments

Notion comments.listComments: arguments, response, policy and SDK examples.

← Comments operations · Get started

Operation notion.list_comments

Provider route: GET /v1/comments. Alter supplies the connection’s credentials and routing.

Install @alter-ai/sdk @alter-ai/notion with npm, or alter-sdk-notion with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { NotionIntegration } from "@alter-ai/notion";
async function execute(input: Parameters<NotionIntegration["comments"]["listComments"]>[0]) {
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
const provider = new NotionIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
const call = await provider.comments.listComments(input);
const result = await call.wait();
return result.bodyJson();
} finally {
await app.close();
}
}
import os
from alter_sdk import App
from alter_sdk_notion import NotionIntegration
async def execute(arguments):
async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
provider = NotionIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
call = await provider.comments.list_comments(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
queryobjectRequired within parentAdditional keys: not allowed
query.block_idstringRequired within parentIdentifier for a Notion block or page.
query.start_cursorstringOptionalIf 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.
query.page_sizeintegerOptionalThe number of items from the full list desired in the response. Maximum: 100
Maximum: 100
Minimum: 1

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
commentModelRequired within parentExpand List views — response body — view
has_morebooleanRequired within parent
next_cursorJSONRequired within parent
next_cursor (anyOf 1)stringAlternativeFormat: uuid
next_cursor (anyOf 2)nullAlternative
objectstringRequired within parentAlways `list`
Must equal: list
request_statusModelOptionalExpand List views — response body — request status
resultsarrayRequired within parent
results[]ModelEach itemExpand Create a comment — response body — object comment — comment Object Response
typestringRequired within parentAlways `comment`
Must equal: comment

Referenced models: List views — response body — view, Create a comment — response body — object comment — comment Object Response, List views — response body — request status

13 more schemas are linked from the tables above, on the schema pages.

List views — response body — view
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
Create a comment — response body — object comment — comment Object Response
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
attachmentsarrayOptionalAny file attachments associated with the comment.
Maximum items: 100
attachments[]objectEach itemAdditional keys: allowed
attachments[].categorystringRequired within parentOne of: `audio`, `image`, `pdf`, `productivity`, `video`
Known values: audio, image, pdf, productivity, video
attachments[].fileModelRequired within parentExpand Get agent — response body — icon value File file
created_byModelRequired within parentExpand Update page — response body — object page created by
The user who created the comment.
created_timestringRequired within parentThe time when the comment was created.
Format: date-time
discussion_idstringRequired within parentThe ID of the discussion thread this comment belongs to.
Format: uuid
display_nameobjectRequired within parentThe display name of the comment.
Additional keys: allowed
display_name.resolved_nameJSONRequired within parent
display_name.resolved_name (anyOf 1)stringAlternative
display_name.resolved_name (anyOf 2)nullAlternative
display_name.typestringRequired within parentOne of: `custom`, `user`, `integration`
Known values: custom, user, integration
has_pending_attachmentsbooleanRequired within parentWhether any file attachments on this comment are still uploading. Pending files are not listed in `attachments` yet. A `comment.updated` webhook is sent when each upload finishes.
idstringRequired within parentThe ID of the comment.
Format: uuid
last_edited_timestringRequired within parentThe time when the comment was last edited.
Format: date-time
objectstringRequired within parentThe comment object type name.
Must equal: comment
original_content_deletedbooleanRequired within parentWhether this comment's original content was deleted.
parentModelRequired within parentExpand Create a comment — response body — object comment parent
The parent of the comment.
property_idstringOptionalThe ID of the database property the comment is on, for comments on a page property. Matches the property's `id` in the page object. Omitted for other comments.
rich_textarrayRequired within parentThe rich text content of the comment.
Maximum items: 100
rich_text[]ModelEach itemExpand Retrieve a page property item — response body — value Title title

Referenced models: Create a comment — response body — object comment parent, Get agent — response body — icon value File file, Update page — response body — object page created by, Retrieve a page property item — response body — value Title title

List views — response body — request status
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
incomplete_reasonstringOptionalWhy the result set is incomplete. Only present when `type` is `incomplete`.
Must equal: query_result_limit_reached
typestringRequired within parentWhether the result set is complete or incomplete. `incomplete` means the response does not include all rows that match the query parameters (e.g. due to a server-side pagination depth limit).
Known values: complete, incomplete
Create a comment — response body — object comment parent
FieldTypePresenceDescription and constraints
$JSONRoot
$ (anyOf 1)ModelAlternativeExpand Create a comment — response body — object comment parent Page Id
$ (anyOf 2)ModelAlternativeExpand Create a comment — response body — object comment parent Block Id

Referenced models: Create a comment — response body — object comment parent Block Id, Create a comment — response body — object comment parent Page Id

Get agent — response body — icon value File file
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
expiry_timestringRequired within parentThe time when the URL will expire.
Format: date-time
urlstringRequired within parentThe URL of the file.
Update page — response body — object page created by
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
idstringRequired within parentFormat: uuid
objectstringRequired within parentAlways `user`
Must equal: user
Retrieve a page property item — response body — value Title title
FieldTypePresenceDescription and constraints
$JSONRoot
$ (allOf 1)ModelAll variants applyExpand Retrieve a page property item — response body — value Title title annotations, href, plain text
$ (allOf 2)JSONAll variants apply
$ (allOf 2) (anyOf 1)ModelAlternativeExpand Retrieve a page property item — response body — value Title title value Text
$ (allOf 2) (anyOf 2)ModelAlternativeExpand Retrieve a page property item — response body — value Title title value Mention
$ (allOf 2) (anyOf 3)ModelAlternativeExpand Retrieve a page property item — response body — value Title title value Equation

Referenced models: Retrieve a page property item — response body — value Title title value Equation, Retrieve a page property item — response body — value Title title value Mention, Retrieve a page property item — response body — value Title title annotations, href, plain text, Retrieve a page property item — response body — value Title title value Text

Create a comment — response body — object comment parent Block Id
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
block_idstringRequired within parentFormat: uuid
typestringRequired within parentAlways `block_id`
Must equal: block_id
Create a comment — response body — object comment parent Page Id
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
page_idstringRequired within parentFormat: uuid
typestringRequired within parentAlways `page_id`
Must equal: page_id
Retrieve a page property item — response body — value Title title value Equation
FieldTypePresenceDescription and constraints
$objectRoot
equationobjectRequired within parentNotion supports inline LaTeX equations as rich text objects with a type value of `equation`.
Additional keys: allowed
equation.expressionstringRequired within parentA KaTeX compatible string.
typestringRequired within parentAlways `equation`
Must equal: equation
Retrieve a page property item — response body — value Title title annotations, href, plain text
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
annotationsModelRequired within parentExpand Retrieve a page property item — response body — value Title title annotations, href, plain text annotations
All rich text objects contain an annotations object that sets the styling for the rich text.
hrefJSONRequired within parentA URL that the rich text object links to or mentions.
href (anyOf 1)stringAlternative
href (anyOf 2)nullAlternative
plain_textstringRequired within parentThe plain text content of the rich text object, without any styling.

Referenced models: Retrieve a page property item — response body — value Title title annotations, href, plain text annotations

List custom emojis — response body — results item
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
idstringRequired within parentThe ID of the custom emoji.
Format: uuid
namestringRequired within parentThe name of the custom emoji.
urlstringRequired within parentThe URL of the custom emoji.

SDK function policy ID: notion.list_comments. Catalog operation: list_comments. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Notion-Version": "2026-03-11"}

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.