taxonomies/get-primary-term reports which term Yoast treats as a post’s primary one in a taxonomy.
The primary term decides the breadcrumb trail and the canonical category in permalinks.
At a glance
| Ability | taxonomies/get-primary-term |
| Toolset | Yoast SEO — toolset/yoast-seo |
| Group | Yoast SEO › Term SEO |
| Requires | Yoast SEO, active on the site |
| Capability | manage_options |
| Safety | Read-only — changes nothing |
| Repeatable | Idempotent — running it twice leaves the same result |
| Ships in | AcrossAI Abilities Manager 0.0.34 and later |
How it works
A post in several categories has to breadcrumb through one of them, and appear under one of them in a %category% permalink. The primary term is that choice.
When it is unset, Yoast picks — usually the lowest term ID, which is essentially arbitrary. So a post in three categories can breadcrumb through the least relevant one without anything looking broken, and nobody notices because the page renders perfectly.
That is the specific failure this read exists for. The breadcrumb is a real navigational and structural signal, and it is wrong silently.
On sites using category-based permalinks the consequence is larger: the primary term is in the URL, so changing it changes the URL.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
post_id | integer | Yes | The post. |
taxonomy | string | Yes | The taxonomy. |
What comes back
| Name | Type | What it is |
|---|---|---|
primary_term | object | The primary term, if one is set. |
is_explicit | boolean | Whether it was set deliberately or inferred by Yoast. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
Which category does post 412 breadcrumb through?
It resolves to one call:
{
"ability": "taxonomies/get-primary-term",
"parameters": {
"post_id": 412,
"taxonomy": "category"
}
}Worth knowing
- Unset means Yoast picks, usually by lowest term ID.
- A wrong breadcrumb is invisible on the page and real to search engines.
- On
%category%permalink sites this term is in the URL. - Read-only.
Related abilities
- Set Primary Term — choose it deliberately
- Update Breadcrumb Settings — how breadcrumbs are built
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category