wp_get_pages: list pages
Lists pages. Identical to wp_get_posts with post_type fixed to page.
Arguments
| Argument | Default | Meaning |
|---|---|---|
status |
publish |
Post status to list |
page |
1 | Page number |
per_page |
20 | Items per page, clamped to 1–100 |
s |
— | Search term |
ids |
— | Restrict to specific IDs |
Passing post_type has no effect; it is overridden.
Permissions
mcp:read and wp:content:read.
Listing published pages needs no further capability. Listing drafts or other statuses requires edit_pages — note this is the pages capability, not edit_posts. A role that can edit posts cannot necessarily list unpublished pages.
What it returns
items and total, each item carrying id, post_type, title, slug, status, date, modified, link and excerpt.
No content, as with every listing.
Why pages need listing more than posts
A site typically has tens of pages and hundreds of posts, so a page listing usually fits in one call — the total is often the whole set.
That makes this a genuinely useful orientation call:
List all the pages with their IDs and titles, then stop.
The result is a map of the site's structure, which is exactly what an assistant needs before editing anything. It also lets you check IDs before a write, which is the single most effective guard against editing the wrong page.
No hierarchy in the response
Pages nest, but the response does not report a parent or produce a tree. The listing is flat.
To understand the structure, look at the link values — the URL path reflects the hierarchy. Or read the navigation menu, which usually mirrors it more usefully. See Site and menu tools.
Finding a page to edit
Two ways, and the ID route is safer:
List the pages and tell me the ID of the one titled "Services".
Search pages for "warranty" and show me which contain it.
Then bound the write to that ID. See Update a page safely.
Using it well
List the published pages with IDs and links.
List the draft pages and tell me the total.
Show me pages 88, 92 and 104.
Common problems
| Symptom | Cause |
|---|---|
| Drafts missing | Default status is publish |
pom_ai_mcp_forbidden |
Listing unpublished pages without edit_pages |
| Fewer than expected | per_page clamps at 100; read total |
| No content in the response | Expected; use wp_get_page |
| No parent or hierarchy shown | Not part of the response; infer from link |