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.

Published, unprotected content can be read with the read scopes. Other statuses require the content type’s editing capability and per-object permission. Actors without permission to edit others’ content are restricted to their own unpublished posts. Password-protected content requires permission to edit that post.

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 counts query matches before individual permission filtering; 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 — unsupported types return an error. Commerce objects use the WooCommerce tools and their separate scopes and controls.

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
Unsupported type error Use a public content type or the dedicated commerce tools
No content in the response Expected; listings omit it
`wp_get_post_types`: list supported post types
Previous
Updates, support, and safe maintenance
Next