wp_count_posts: count posts
Returns how many posts exist per status, without listing them. The cheapest way to size a job before starting it.
Arguments
| Argument | Default | Meaning |
|---|---|---|
post_type |
post |
Any public post type |
Permissions
mcp:read and wp:content:read. No further capability, and no write gate — it is read-only.
What it returns
A counts object keyed by post status: publish, draft, pending, private, trash and any other status registered on the site.
A non-public post type returns empty counts rather than an error, which is worth noticing — an empty result may mean "none" or "not reachable".
Why call it first
An assistant asked to "update the posts in this category" will start updating. Asking for a count first turns an open-ended job into a known one:
How many published posts are there? Do not change anything yet.
The answer changes what you agree to. Forty is a session; four hundred is a project that needs planning, batching and a pilot.
It also costs almost nothing: one read call, against the higher read rate limit, returning a small object.
Reading the statuses
The breakdown is often more informative than the total:
- A large
draftcount means unfinished work that a "update all posts" instruction would touch. - A large
trashcount means deletions that have not been purged. - A
pendingcount means an editorial queue.
Before any bulk instruction, know which statuses are in scope. See wp_get_posts, which defaults to publish only.
Custom post types
Pass post_type to count anything public:
Count the posts of type "project".
To find out which types exist, call wp_get_post_types first.
Using it well
Count posts and pages, and show me both breakdowns.
How many drafts are there for the "project" post type?
Before a batch:
Count them, then list the first ten with IDs, then stop.
That sequence — count, sample, stop — is the standard opening for any bulk content job. See Prompt patterns for multi-step MCP work.
What it does not do
- No filtering by category, author, date or search term. It counts a post type.
- No IDs. Use
wp_get_posts. - No term counts. See
wp_count_terms. - No media counts. See Media tools.
Common problems
| Symptom | Cause |
|---|---|
| Empty counts | The post type is not public, or does not exist |
| The total disagrees with a listing | The listing defaults to publish only |
| Counts include trashed items | Correct; read the trash key separately |