List Child Pages
List the direct child pages under one parent to browse the workspace directory level by level.
List Child Pages
When to use
Use this endpoint to list one known parent page's children. MCP callers must pass parent_id; when the user asks for the workspace directory or sidebar, use List Sidebar Section Pages instead. Direct API clients may still omit parent_id for the legacy workspace-root view.
If you already know what you are looking for, search is more direct. If you need a page's body content such as paragraphs, lists or images, use Get Block Children instead: that endpoint returns every block, while this one returns page-level nodes only.
Endpoint
| Item | Value |
|---|---|
| Method | GET |
| Path | /v2/pages |
| Request body | None |
| Returns | list of page nodes |
| Scope | pages.read |
Permissions
Requires pages.read. Results include only the nodes this credential may read: a workspace-scoped integration sees the whole directory, while a page-scoped credential sees only the subtrees it was granted.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
parent_id |
string | No for direct API; required by MCP | Parent page UUID. Omission is retained only for the legacy direct API workspace-root view. |
page_size |
integer | No | Items per page, 1-100, default 20. |
start_cursor |
string | No | The next_cursor from a previous response. |
Response
{
"object": "list",
"results": [
{
"object": "page",
"id": "11111111-1111-4111-8111-111111111111",
"page_type": "page",
"title": "Product docs",
"icon": { "type": "emoji", "emoji": "đź“„" },
"parent": { "type": "workspace", "workspace": true },
"url": "https://buildin.ai/11111111-1111-4111-8111-111111111111",
"created_time": "2026-04-09T09:30:00.000Z",
"last_edited_time": "2026-04-10T02:15:00.000Z",
"has_children": true
}
],
"next_cursor": null,
"has_more": false
}
page_type is one of page, folder, database, mind_map.
Behavior
- One level only. When
has_childrenistrue, pass that node'sidasparent_idto list the next level. - Non-page container blocks are transparent. Blocks such as columns and toggle lists do not appear in the results; the child pages inside them are lifted to the current level, matching how the product sidebar presents them.
has_childrencounts readable child pages only. It isfalsewhen every child page is unreadable, so you never drill into an empty level.- Sibling order matches the product sidebar.
- Pagination applies to this single level;
next_cursoris the id of the last node on the page.
Errors
400 validation_error:parent_idis not a valid UUID.401 unauthorized: the token is invalid or expired.403 forbidden: no read access to the page referenced byparent_id.404 not_found: the page referenced byparent_iddoes not exist or belongs to another workspace.