wp_get_categories: list categories
Lists category terms.
Arguments
| Argument | Default | Meaning |
|---|---|---|
per_page |
20 | Number of terms, clamped to 1–100 |
search |
— | Filter by search term |
hide_empty |
false | Exclude terms with no posts |
Permissions
mcp:read and wp:content:read. No WordPress capability required.
What it returns
items only. Each term carries id, taxonomy, name, slug, description and count.
There is no total. Unlike post and media listings, a term listing does not tell you how many exist beyond the page you asked for. Use wp_count_terms for the size.
Read this before creating anything
The most valuable use of this tool is preventing duplicate terms.
An assistant asked to categorise posts will create categories it cannot find. Without reading the existing list first, it produces "News", "news" and "Company News" as three separate terms — each with its own archive page and its own slug.
List the existing categories with their IDs and post counts, then stop.
Then state the boundary explicitly:
Only use these categories. If a post does not fit any, tell me rather than creating a new one.
count is the field that matters
It reports how many published posts use the term, and it is what turns a vague decision into an informed one:
- A high count means renaming affects many archive pages, and deleting is a structural change.
- A count of zero means the term is unused and safe to remove.
- A count of one or two usually means a term created by accident.
Before any term deletion, read the count. See wp_delete_term.
hide_empty defaults to showing everything
Unused terms are included unless you pass hide_empty. That is the right default for an audit — the empty terms are exactly the ones worth reviewing.
Pass hide_empty: true when you want the taxonomy as a visitor experiences it.
Hierarchy is not reported
Categories nest, but the response carries no parent field and no tree.
So a listing cannot tell you which categories are children of which. If the structure matters — before creating a child, or before deleting a parent — check it in the WordPress admin.
This is a real gap when reorganising a nested taxonomy, and worth knowing before promising an assistant can restructure one.
Finding a term ID
wp_add_post_terms takes term IDs, not names, so this listing is usually the step that resolves one:
List the categories and tell me the ID of "Maintenance".
If the search returns nothing, do not let the assistant proceed by creating the term unless you meant it to.
Using it well
List the categories with their IDs and counts.
Search the categories for "service".
List the categories that have no posts.
Common problems
| Symptom | Cause |
|---|---|
| Fewer terms than expected | per_page clamps at 100, and there is no total |
| Empty terms missing | hide_empty was passed |
| No parent information | Not part of the response shape |
| Duplicate-looking terms | Created without reading the existing list first |