wp_get_tags: list tags
Lists tag terms. Identical to wp_get_categories with the taxonomy fixed to post_tag.
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, with each term carrying id, taxonomy, name, slug, description and count. No total — use wp_count_terms.
Tags are flat, and usually messy
The difference from categories is not mechanical, it is practical. Tags are non-hierarchical, unmoderated and accumulate: most sites have far more tags than categories, and a long tail of tags used once.
That shapes how this tool is used. Where a category listing usually fits in one page, a tag listing frequently does not — and the tags that matter are a minority of what exists.
Start by finding out the scale:
Count the tags, then list the first 50 with their post counts, and stop.
The single-use tail
Tags with a count of one are the characteristic problem: typos, near-synonyms, and terms invented once and never reused.
They are worth reviewing, and they are also the reason an unbounded cleanup instruction is dangerous. "Remove the unused tags" sounds reasonable; a tag with one post is not unused, and deleting it removes that post's classification permanently.
Read the counts before deciding anything, and name IDs rather than criteria. See wp_delete_term.
Preventing new duplicates
The same rule as categories, and it matters more here because tags multiply faster:
List the existing tags first. Only use tags that already exist. If you think a new one is needed, tell me the name and wait.
Without that boundary, an assistant tagging twenty posts creates a dozen near-duplicates of tags that were already there in a different case or with a plural.
search is the practical filter
On a site with hundreds of tags, listing is not how you find one. Search is:
Search the tags for "maintenance" and show me the IDs and counts.
This is also the check to run before letting anything create a tag — if a close match exists, use it.
No hierarchy, no parent
Tags cannot nest, so unlike categories there is no missing parent information to worry about. Passing parent to a tag operation is meaningless.
Using it well
List the tags with counts, ordered as returned.
Search the tags for "spring".
How many tags have only one post?
That last question needs the counts, which the listing provides — but remember it can only answer within the page you fetched.
Common problems
| Symptom | Cause |
|---|---|
| Far fewer tags than the site has | per_page clamps at 100, and there is no total |
| Empty tags missing | hide_empty was passed |
| Duplicate-looking tags | Created without reading the existing list |
| A tag you expect is absent | Try search; the listing is only one page |