---
title: "Get your achievements (v3)"
method: GET
path: "/v3/achievements"
tags: ["achievements"]
---

# Get your achievements (v3)

`GET /v3/achievements`

Returns your complete achievement list using the enhanced v3 API.

## v3 vs v2 Differences

The v3 achievements API provides:
- **Direct achievement data** - Raw achievement records without title grouping
- **Contract version 2** - Uses the newer Xbox Live achievements contract
- **Simplified response** - Flatter data structure for easier parsing

## Response Structure

Returns an array of achievement objects with:
- `id` - Unique achievement identifier
- `name` - Achievement display name
- `description` - How to unlock the achievement
- `isUnlocked` - Whether you've earned it
- `timeUnlocked` - When it was earned (if unlocked)
- `gamerscore` - Points awarded

## Pagination

Xbox returns 32 achievements per page by default. The response carries a
`pagingInfo.continuationToken`; pass it back as the `continuationToken` query
param to fetch the next page:

```
GET /v3/achievements
GET /v3/achievements?continuationToken=32
GET /v3/achievements?continuationToken=64
```

Keep following `pagingInfo.continuationToken` until it comes back `null`, which
signals the last page. `totalRecords` tells you how many achievements exist in total.

Use `maxItems` to request a larger page and cut down the number of round trips
(e.g. `?maxItems=200`). Omit it to keep Xbox's default of 32.

The token must be sent as a query parameter - it is not read from a header.

## When to Use v3 vs v2

- Use **v3** when you need raw achievement data
- Use **v2** when you want achievements grouped by title

## Query parameters

- `continuationToken` string
- `maxItems` union
  - string, numeric
  - number

## Response `200`

Achievement list

- ApiResponse — Standard API response wrapper. All endpoints return responses in this format.
  - `content` unknown, required
  - `code` integer, required — HTTP status code from the upstream API. Common values: 200 (success), 400 (bad request), 401 (unauthorized), 404 (not found), 410 (deprecated/gone), 429 (rate limited), 500 (server error)

## Other responses

- `401` — Invalid or missing API key
- `429` — Rate limit exceeded

---

[API](https://skmtc.dev/xbl/apis/openxbl-api.md) · [All operations](https://skmtc.dev/xbl/apis/openxbl-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/xbl/openxbl-api/revisions/e5df7bdca559/schema)