learndash/get-achievement fetches a single achievement definition: its trigger, points, occurrence limit, badge image, popup message, the five scope keys, and its award count.
The scope keys are where most misconfiguration lives.
At a glance
| Ability | learndash/get-achievement |
| Toolset | LearnDash — toolset/learndash |
| Group | LearnDash › Achievements |
| Requires | AcrossAI Pro, plus LearnDash LMS active on the site |
| Capability | manage_options |
| Safety | Read-only — changes nothing |
| Repeatable | Idempotent — running it twice leaves the same result |
| Ships in | AcrossAI Pro 0.9.16 and later |
How it works
There are five: course, lesson, topic, quiz and group. Each can hold a post ID to restrict the badge to that object, the string all as a wildcard, or nothing at all.
Nothing at all means the key is not applicable to this trigger — a login-streak badge has no course scope — which is a different state from all, and reading one as the other is how a badge ends up scoped to nothing.
A badge scoped to a course that has since been deleted never fires and looks correctly configured.
The award count confirms whether the configuration works in practice, which the definition alone cannot.
The popup message is what the learner sees when they earn it, and the badge image is what appears on their profile — both are presentation rather than logic, and both are commonly left unset on badges created programmatically.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
achievement_id | integer | Yes | The achievement. |
What comes back
| Name | Type | What it is |
|---|---|---|
achievement | object | Trigger, points, occurrence limit, image, message, scope keys and award count. |
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:
How is this badge configured?
It resolves to one call:
{
"ability": "learndash/get-achievement",
"parameters": {
"achievement_id": 900
}
}Worth knowing
- An empty scope key and
allmean different things. - A badge scoped to a deleted course looks fine and never fires.
- The award count is the only proof the configuration works.
- Requires the LearnDash Achievements add-on.
Related abilities
- LearnDash Manage Achievement — change the scope
- LearnDash List Triggers — what each trigger scopes by
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category