wp_get_posts: list posts
Lists posts and public custom post types, with filtering and pagination.
Arguments
| Argument | Default | Meaning |
|---|---|---|
post_type |
post |
Any public post type |
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 |
Permissions
mcp:read and wp:content:read.
Listing published items needs no further capability. Listing any other status requires edit_posts, or edit_pages when listing pages.
What it returns
items, an array of posts, and total, the number of matches across all pages.
Each item carries id, post_type, title, slug, status, date, modified, link and excerpt.
Listings do not include content. To read the body of a post, call wp_get_post for it.
Read the total
total is the real number of matches; items is at most one page of them. An assistant that lists once and reports on "all the posts" has seen up to a hundred.
For a job over many records, get the total first and work in explicit pages:
List the posts in this category and tell me the total, then stop.
Non-public post types are invisible
Only public post types are reachable. A post type registered as non-public does not appear in wp_get_post_types and cannot be listed here — passing it falls back to post rather than erroring, which is worth knowing when a listing returns unexpected content.
Check the post_type on the returned items if the results look wrong.
Filtering
By status. Pass status to see drafts, pending or private items. Remember the capability requirement.
By search term. s runs a WordPress search across the post type.
By ID. ids restricts the query to a specific set, which is the precise way to re-read a known group after a batch operation.
Using it well
List the 10 most recent published posts with their IDs and titles.
List the draft pages and tell me the total.
List posts 412, 415 and 418.
Before a bulk job:
List the posts in the Guides category with IDs, tell me the total, and stop. Do not change anything.
What it does not do
- No content. Use
wp_get_post. - No taxonomy filtering argument. Filter by search term, or read terms separately and use
ids. - No ordering argument. Results follow the query's default order.
- No meta. See Comment and meta tools.
Common problems
| Symptom | Cause |
|---|---|
| Fewer items than expected | per_page clamps at 100; read total |
| Drafts missing | Default status is publish; pass status |
pom_ai_mcp_forbidden |
Listing non-published content without the capability |
| Unexpected post type in results | A non-public type was requested and fell back to post |
| No content in the response | Expected; listings omit it |
Related
wp_get_postwp_count_poststo size a job without listingwp_searchto search across types