wp_get_menu_items: list menu items
Lists every item in one menu, with its position in the hierarchy.
Arguments
| Argument | Required | Meaning |
|---|---|---|
menu_id |
Yes | The menu, from wp_get_menus |
Permissions
mcp:read and wp:content:read, plus edit_theme_options.
What it returns
An items list. Each item carries:
| Field | Meaning |
|---|---|
id |
The menu item ID |
title |
The label shown to visitors |
url |
Where it points |
parent |
The parent item's ID, or 0 for top level |
object |
What kind of thing it links to |
object_id |
The ID of that thing |
order |
Its position |
This response has hierarchy, and taxonomy listings do not
Worth calling out because it is the exception. Term listings expose no parent at all; menu items do.
parent and order together describe the whole structure, which means an assistant reading this listing genuinely knows the menu's shape — and can therefore make a correct edit rather than a guess.
Always read this before any menu write.
object and object_id distinguish two kinds of item
A menu item either points at something in WordPress or at an arbitrary URL:
- A linked item has
objectset topage,post,categoryand so on, withobject_idnaming the specific record. WordPress keeps its URL correct if the target's permalink changes. - A custom item has
objectofcustomand a literalurl. Nothing keeps it correct.
That distinction matters when auditing: custom items are the ones that silently rot when a page's slug changes, and they are what wp_create_menu_item produces by default.
Reading the structure before an edit
Show me every item in menu 3 with its ID, title, URL, parent and order.
From that you can answer the questions a safe edit needs:
- Which item is the one to change?
- Does it have children that would be orphaned if removed?
- What is the current order, so a reorder can be expressed as a complete list?
- Are any URLs pointing at drafts or missing pages?
Auditing for dead links
The listing gives you every URL in one response, which makes this a quick audit:
List the items in menu 3 and tell me which point at URLs rather than at WordPress objects.
Then check those manually. Linked items generally survive content changes; custom ones do not.
What it does not do
- No validation that the targets exist. A menu item pointing at a deleted page is listed like any other.
- No indication of which menu location the menu is assigned to.
- No language information on a multilingual site — each language's menu is a separate menu.
Using it well
Pair it with the menus listing at the start of any navigation session:
List the menus, then show me the items in the main menu. Do not change anything yet.
Then bound the write to specific item IDs. See Edit a navigation menu.
Common problems
| Symptom | Cause |
|---|---|
pom_ai_mcp_forbidden |
No edit_theme_options |
| An empty list | The menu has no items, or the ID is wrong |
| Items you do not see on the site | The menu is not assigned to a theme location |
parent values you did not expect |
The menu is deeper than it appears when rendered |