> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/apis/apis/badges/user-progress.md).
# User Progress
Operations for tracking user badge achievements and progress
## Get user's badge progress
> Returns detailed progress information for all badges associated with a specific user address.\
> \
> This endpoint provides comprehensive tracking data including:\
> \- \*\*Achieved badges\*\*: Badges the user has earned (at least one step completed)\
> \- \*\*Progress tracking\*\*: Current steps completed vs. target steps for next tier\
> \- \*\*Tier progression\*\*: For tiered badges, shows which tiers have been completed and when\
> \- \*\*Completion status\*\*: Whether the badge/tier is fully completed\
> \- \*\*Asset information\*\*: Current badge/tier images and metadata\
> \
> The response is divided into two categories:\
> \- \`achieved\`: Badges with at least one step or tier completed\
> \- \`notAchieved\`: Badges not yet started (only included if \`includeNotAchieved=true\`)\
> \
> For tiered badges, the progress tracks movement through tiers (Starter → Bronze → Silver → Gold → Platinum → Diamond).\
> For single-tier badges, it tracks completion of a specific criteria.
```json
{"openapi":"3.1.0","info":{"title":"Decentraland Badges API","version":"1.0.0"},"tags":[{"name":"User Progress","description":"Operations for tracking user badge achievements and progress"}],"servers":[{"url":"https://badges.decentraland.org","description":"Production environment"},{"url":"https://badges.decentraland.zone","description":"Development environment"}],"security":[],"paths":{"/users/{address}/badges":{"get":{"tags":["User Progress"],"summary":"Get user's badge progress","description":"Returns detailed progress information for all badges associated with a specific user address.\n\nThis endpoint provides comprehensive tracking data including:\n- **Achieved badges**: Badges the user has earned (at least one step completed)\n- **Progress tracking**: Current steps completed vs. target steps for next tier\n- **Tier progression**: For tiered badges, shows which tiers have been completed and when\n- **Completion status**: Whether the badge/tier is fully completed\n- **Asset information**: Current badge/tier images and metadata\n\nThe response is divided into two categories:\n- `achieved`: Badges with at least one step or tier completed\n- `notAchieved`: Badges not yet started (only included if `includeNotAchieved=true`)\n\nFor tiered badges, the progress tracks movement through tiers (Starter → Bronze → Silver → Gold → Platinum → Diamond).\nFor single-tier badges, it tracks completion of a specific criteria.\n","operationId":"getUserBadges","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"User's Ethereum address (wallet address)"},{"name":"includeNotAchieved","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"If true, includes badges that the user hasn't started working toward yet"}],"responses":{"200":{"description":"Successfully retrieved user's badge progress","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Container for user's badge progress, divided by achievement status","properties":{"achieved":{"type":"array","description":"Badges with at least one step or tier completed","items":{"type":"object","description":"Detailed progress tracking for a single badge","properties":{"id":{"type":"string","description":"Badge identifier"},"name":{"type":"string","description":"Badge name"},"description":{"type":"string","description":"Badge description"},"category":{"type":"string","enum":["Explorer","Collector","Creator","Socializer","Builder"],"description":"Badge category"},"isTier":{"type":"boolean","description":"Whether this badge has multiple tiers"},"completedAt":{"type":["number","null"],"description":"Unix timestamp (milliseconds) when badge was fully completed, null if not completed"},"assets":{"type":"object","description":"Asset URLs for badge imagery in different formats","properties":{"2d":{"type":"object","description":"2D badge assets","properties":{"normal":{"type":"string","description":"Standard 2D badge image URL"}},"required":["normal"]},"3d":{"type":"object","description":"3D badge assets for rendering in-world","properties":{"normal":{"type":"string","description":"3D model file URL"},"hrm":{"type":"string","description":"Height/roughness/metallic texture map URL"},"basecolor":{"type":"string","description":"Base color texture map URL"}},"required":["normal","hrm","basecolor"]}}},"progress":{"type":"object","description":"Progress tracking information","properties":{"achievedTiers":{"type":"array","description":"List of tiers achieved (only for tiered badges)","items":{"type":"object","properties":{"tierId":{"type":"string"},"completedAt":{"type":"number","description":"Unix timestamp (milliseconds) when tier was completed"}}}},"stepsDone":{"type":"integer","description":"Number of steps/actions completed"},"nextStepsTarget":{"type":["integer","null"],"description":"Target steps for next tier/completion (null if fully completed)"},"totalStepsTarget":{"type":"integer","description":"Total steps required for full badge completion"},"lastCompletedTierAt":{"type":["number","null"],"description":"Timestamp of last completed tier (tiered badges only)"},"lastCompletedTierName":{"type":["string","null"],"description":"Name of last completed tier (tiered badges only)"},"lastCompletedTierImage":{"type":["string","null"],"description":"Image URL of last completed tier (tiered badges only)"}}}},"required":["id","name","description","category","isTier","progress"]}},"notAchieved":{"type":"array","description":"Badges not yet started (only included if includeNotAchieved=true)","items":{"type":"object","description":"Detailed progress tracking for a single badge","properties":{"id":{"type":"string","description":"Badge identifier"},"name":{"type":"string","description":"Badge name"},"description":{"type":"string","description":"Badge description"},"category":{"type":"string","enum":["Explorer","Collector","Creator","Socializer","Builder"],"description":"Badge category"},"isTier":{"type":"boolean","description":"Whether this badge has multiple tiers"},"completedAt":{"type":["number","null"],"description":"Unix timestamp (milliseconds) when badge was fully completed, null if not completed"},"assets":{"type":"object","description":"Asset URLs for badge imagery in different formats","properties":{"2d":{"type":"object","description":"2D badge assets","properties":{"normal":{"type":"string","description":"Standard 2D badge image URL"}},"required":["normal"]},"3d":{"type":"object","description":"3D badge assets for rendering in-world","properties":{"normal":{"type":"string","description":"3D model file URL"},"hrm":{"type":"string","description":"Height/roughness/metallic texture map URL"},"basecolor":{"type":"string","description":"Base color texture map URL"}},"required":["normal","hrm","basecolor"]}}},"progress":{"type":"object","description":"Progress tracking information","properties":{"achievedTiers":{"type":"array","description":"List of tiers achieved (only for tiered badges)","items":{"type":"object","properties":{"tierId":{"type":"string"},"completedAt":{"type":"number","description":"Unix timestamp (milliseconds) when tier was completed"}}}},"stepsDone":{"type":"integer","description":"Number of steps/actions completed"},"nextStepsTarget":{"type":["integer","null"],"description":"Target steps for next tier/completion (null if fully completed)"},"totalStepsTarget":{"type":"integer","description":"Total steps required for full badge completion"},"lastCompletedTierAt":{"type":["number","null"],"description":"Timestamp of last completed tier (tiered badges only)"},"lastCompletedTierName":{"type":["string","null"],"description":"Name of last completed tier (tiered badges only)"},"lastCompletedTierImage":{"type":["string","null"],"description":"Image URL of last completed tier (tiered badges only)"}}}},"required":["id","name","description","category","isTier","progress"]}}},"required":["achieved","notAchieved"]}}}}}},"404":{"description":"User address not found or invalid","content":{"application/json":{"schema":{"type":"object","description":"Error response object","properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"}},"required":["error"]}}}}}}}}}
```
## Get user's latest achieved badges
> Returns a lightweight preview of the user's most recently achieved badges.\
> \
> This endpoint is optimized for displaying user achievements in UI components like profile cards or leaderboards. It provides:\
> \- Badge ID, name, and display image\
> \- Tier name (if applicable) for the most recently achieved tier\
> \- Appropriate badge imagery for the current tier level\
> \
> Unlike \`/users/{address}/badges\`, this endpoint:\
> \- Returns only completed badges (no progress tracking)\
> \- Includes only the latest achievements\
> \- Has a lighter payload optimized for quick loading\
> \- Is ideal for preview cards, tooltips, and summary displays
```json
{"openapi":"3.1.0","info":{"title":"Decentraland Badges API","version":"1.0.0"},"tags":[{"name":"User Progress","description":"Operations for tracking user badge achievements and progress"}],"servers":[{"url":"https://badges.decentraland.org","description":"Production environment"},{"url":"https://badges.decentraland.zone","description":"Development environment"}],"security":[],"paths":{"/users/{address}/preview":{"get":{"tags":["User Progress"],"summary":"Get user's latest achieved badges","description":"Returns a lightweight preview of the user's most recently achieved badges.\n\nThis endpoint is optimized for displaying user achievements in UI components like profile cards or leaderboards. It provides:\n- Badge ID, name, and display image\n- Tier name (if applicable) for the most recently achieved tier\n- Appropriate badge imagery for the current tier level\n\nUnlike `/users/{address}/badges`, this endpoint:\n- Returns only completed badges (no progress tracking)\n- Includes only the latest achievements\n- Has a lighter payload optimized for quick loading\n- Is ideal for preview cards, tooltips, and summary displays\n","operationId":"getUserBadgesPreview","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"User's Ethereum address"}],"responses":{"200":{"description":"Successfully retrieved user's badge preview","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"latestAchievedBadges":{"type":"array","items":{"type":"object","description":"Lightweight badge preview for UI display","properties":{"id":{"type":"string","description":"Badge identifier"},"name":{"type":"string","description":"Badge name"},"tierName":{"type":["string","null"],"description":"Name of the achieved tier (if applicable)"},"image":{"type":"string","description":"URL to the badge or tier image"}},"required":["id","name","image"]}}}}}}}}},"404":{"description":"User address not found or invalid","content":{"application/json":{"schema":{"type":"object","description":"Error response object","properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"}},"required":["error"]}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.decentraland.org/apis/apis/badges/user-progress.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.