> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bottari.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List comments

> Read comments on a page or block, oldest first. Requires Read comments.

Reads comments and replies in creation order. Requires **Read comments**. Writing comments isn't available.

**Authorization** `string` *required*

`Bearer <token>`. See [Tokens](https://developers.bottari.ai/auth/tokens.md).

**Bottari-Version** `string`

Optional. Only `2026-03-11` is accepted. Without it, the current version is used. A different value returns 400.

**block\_id** `string` *required*

A page ID or block ID. The format isn't checked, and an unknown ID returns 404.

**page\_size** `number` (default: 100)

1 to 100.

**start\_cursor** `string`

`next_cursor` from the previous response. It's the ID of the next comment.

## What's returned

| `block_id` | Result |
| - | - |
| Page ID | Comments on the page and their replies. Comments whose block is gone also move here. Comments on existing blocks don't appear. |
| Block ID | Comments on that block and their replies. A comment on text counts as a comment on the block holding that text. |

* Resolved threads are left out of the list, including replies. [Retrieve a comment](https://developers.bottari.ai/api-reference/comments/retrieve.md) can still read them.
* Deleted comments are left out of the list. Deleting a thread also deletes its replies.
* If a comment's block is gone, reading by that block ID returns `rich_text: []`. Reading by page ID or with [Retrieve a comment](https://developers.bottari.ai/api-reference/comments/retrieve.md) returns the text.
* `discussion_id` differs per thread for page comments. A reply's `discussion_id` matches the first comment of its thread.
* Comments on a trashed row have `rich_text: []` and `original_content_deleted: true`. Restoring the row brings the text back.

## Comment object

For a comment on text in a subpage card, `parent` has the form `{document id}.{block}`. Reading a block with this ID returns 404, but you can use it as `block_id` here.

**id** `string`

The comment ID.

**parent** `object`

`{ "type": "page_id", "page_id": "..." }` or `{ "type": "block_id", "block_id": "..." }`. A reply matches the first comment of its thread.

**discussion\_id** `string`

The thread ID, which matches the first comment's ID.

**created\_time** `string`

Creation time, in UTC, truncated to the minute.

**last\_edited\_time** `string`

Last edit time. If it was never edited, this is the creation time.

**created\_by** `object`

`{ "object": "user", "id": "..." }`.

**rich\_text** `object[]`

Rich text items split every 2,000 characters, with a newline item between paragraphs. A comment with only attachments has `[]`.

**display\_name** `object`

`{ "type": "user", "resolved_name": "Name" }` for a person, `{ "type": "integration", "resolved_name": "보따리" }` for a comment Bottari wrote. With user information set to **None**, a person's `resolved_name` is empty.

**original\_content\_deleted** `boolean`

`true` if the original text or block is gone, or the row is in the trash.

**has\_pending\_attachments** `boolean`

Always `false`.

## Errors

| Status | `code` | Cause |
| - | - | - |
| 400 | `validation_error` | `block_id` is missing, `page_size` is wrong, or `start_cursor` isn't a comment in this document. |
| 403 | `restricted_resource` | **Read comments** is off. |
| 404 | `object_not_found` | The page or block doesn't exist, or the integration can't read it. |

See [Common rules](https://developers.bottari.ai/api-reference/overview.md#errors) for shared errors.

```bash curl theme={null}
curl "https://api.bottari.ai/v1/comments?block_id=exampleRow01&page_size=50" \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11"
```

```json 200 theme={null}
{
  "object": "list",
  "results": [
    {
      "object": "comment",
      "id": "exampleCmt01",
      "parent": {
        "type": "page_id",
        "page_id": "exampleRow01"
      },
      "discussion_id": "exampleCmt01",
      "created_time": "2026-01-15T02:30:00.000Z",
      "last_edited_time": "2026-01-15T02:30:00.000Z",
      "created_by": {
        "object": "user",
        "id": "11111111-1111-4111-8111-111111111111"
      },
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "Looks good.",
            "link": null
          },
          "annotations": {
            "bold": true,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
          },
          "plain_text": "Looks good.",
          "href": null
        }
      ],
      "display_name": {
        "type": "user",
        "resolved_name": "Alex Kim"
      },
      "original_content_deleted": false,
      "has_pending_attachments": false
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "type": "comment",
  "comment": {},
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```

```json 400 theme={null}
{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "query failed validation: query.block_id should be defined, instead was `undefined`.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```

```json 403 theme={null}
{
  "object": "error",
  "status": 403,
  "code": "restricted_resource",
  "message": "Insufficient permissions for this endpoint.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.