Get Block Children

Use Case

Use this endpoint to page through the direct child blocks under a page block or any block that can contain children.

Endpoint

Permissions

Requires blocks.read and access to the parent block.

Parameters

Response Example

{
  "object": "list",
  "results": [
    {
      "object": "block",
      "id": "44444444-4444-4444-8444-444444444444",
      "parent": {
        "type": "page_id",
        "page_id": "11111111-1111-4111-8111-111111111111"
      },
      "created_time": "2026-04-09T08:00:00.000Z",
      "last_edited_time": "2026-04-09T09:30:00.000Z",
      "created_by": {
        "object": "user",
        "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
      },
      "last_edited_by": {
        "object": "user",
        "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
      },
      "has_children": false,
      "in_trash": false,
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "Project kickoff notes",
              "link": null
            },
            "plain_text": "Project kickoff notes",
            "href": null
          }
        ],
        "color": "default"
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Behavior

• Only direct children are returned.
• Nested descendants require additional calls for child blocks with has_children: true.
• Use pagination fields to traverse large pages.

Errors

• 400 validation_error: invalid pagination parameters.
• 401 unauthorized: invalid or expired token.
• 403 forbidden: missing blocks.read or no access.
• 404 not_found: parent block does not exist.

Related Docs

Prerequisites

• Get Block

Next Steps

• Append Block Children

References

• Block Types
• Conventions