# SteamSets Docs

> Build on the SteamSets API: Steam accounts, badges, leaderboards, and live activity.

# SteamSets API
Source: https://docs.steamsets.com/

The SteamSets API gives you the same data that powers [steamsets.com](https://steamsets.com): Steam profiles, badge collections, leaderboards, trading card owners, and the live activity feed. Every endpoint takes a JSON body and returns JSON, so any HTTP client works.

**[Quickstart](/quickstart)**

Get an API key and send your first request.

**[API reference](/reference)**

Every public endpoint, with schemas and a Try it panel.

**[Authentication](/authentication)**

Send your API key as a bearer token.

**[TypeScript SDK](/sdk)**

Call the API with typed requests and responses.

## How requests look

All endpoints live under `https://api.steamsets.com/v1`. Each endpoint name has the form `<resource>.<action>`, for example `account.getInfo` or `leaderboard.getAccountLeaderboard`. Most endpoints use `POST` with a JSON body, also when they only read data, so that complex filters do not need to fit in a query string.

```bash
curl https://api.steamsets.com/v1/account.getInfo \
  -H "Authorization: Bearer $STEAMSETS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": {"steamId64": "76561199176433616"}}'
```

## What you can build

- Profile widgets that show a Steam level, badge count, and leaderboard rank.
- Badge trackers that compare collections between up to 10 accounts.
- Bots that post leaderboard changes or live site activity to a Discord server.
- Market tools that find which accounts own a trading card or booster pack.

---

# Authentication
Source: https://docs.steamsets.com/authentication

The API uses bearer tokens. Send your API key in the `Authorization` header of each request:

```http
Authorization: Bearer your-key
```

A request without a valid key gets a `401 Unauthorized` response.

## Get a key

Create a developer app in [Settings, API keys](https://steamsets.com/settings/api-keys) on steamsets.com. Each developer app has one API key. SteamSets shows the key one time only, when you create it or generate a new one.

## Keep the key secret

Your key identifies your developer app, and all requests with it count toward the limits of that app.

- Keep the key on a server. Do not put it in browser code, a mobile app, or a public repository.
- Read the key from an environment variable or a secret store.
- If a key leaks, generate a new key in [Settings, API keys](https://steamsets.com/settings/api-keys).

:::note
Some endpoints in the live API are for the steamsets.com website only and need a browser session. This reference does not show them, because an API key cannot call them.
:::

## Try it in the reference

Each page in the [API reference](/reference) has a **Try it** panel. Paste your key into the panel to send real requests from your browser. The key stays in memory and goes only to `api.steamsets.com`. Select **Remember on this device** to keep it in local storage for your next visit.

---

# Errors
Source: https://docs.steamsets.com/errors

When a request fails, the API returns a `4xx` or `5xx` status with a body of type `application/problem+json`. The body follows [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457), so the same fields are present on every endpoint.

```json
{
  "$schema": "https://api.steamsets.com/schemas/ErrorModel.json",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [
    {
      "location": "body.id.steamId64",
      "message": "expected length >= 17",
      "value": "7656119"
    }
  ]
}
```

| Field | Description |
| --- | --- |
| `status` | The HTTP status code, repeated in the body. |
| `title` | A short summary of the problem type. |
| `detail` | A human-readable explanation of this problem. |
| `errors` | For validation errors, one entry for each invalid field, with its `location` in the request. |

## Status codes

| Status | Meaning | What to do |
| --- | --- | --- |
| `400` | The request body is not valid JSON, or a value has the wrong type. | Fix the request. |
| `401` | The API key is missing or not valid. | Send a valid key. See [Authentication](/authentication). |
| `403` | The key is valid, but it cannot use this endpoint. | Use a different endpoint, or ask for access. |
| `404` | The account, badge, or app does not exist on SteamSets. | Check the identifier. |
| `422` | One or more fields failed validation. | Read `errors` to find the fields. |
| `429` | You sent too many requests. | Wait, then send the request again. See [Rate limits](/rate-limits). |
| `500` | The API had an internal problem. | Send the request again later. |

## Request IDs

Each response has a `request-id` header. Include it when you report a problem, so that we can find the request in our logs.

---

# Locations
Source: https://docs.steamsets.com/locations

SteamSets takes the location of an account from its Steam profile. A location has up to four levels: a region, a country, a state, and a city. You use these names to get a leaderboard for one location, for example the top accounts by XP in Germany.

## Download all locations

These files contain every location that the leaderboard endpoints accept. We generate them again each time the docs are deployed.

| File | Contents |
| --- | --- |
| [`/locations/locations.json`](/locations/locations.json) | All regions, countries (with their country code), and states. |
| [`/locations/cities.json`](/locations/cities.json) | All cities, each with its state, country, and region. The file is about 4 MB, or 300 KB with gzip. |

```bash
curl -O https://docs.steamsets.com/locations/locations.json
```

`locations.json` has this shape:

```json
{
  "regions": ["Africa", "Americas", "Antarctic", "Asia", "Europe", "Oceania"],
  "countries": [{ "name": "Germany", "code": "DE", "region": "Europe" }],
  "states": [{ "name": "Baden-Wurttemberg", "country": "Germany", "region": "Europe" }]
}
```

Each entry in `cities.json` has the form `{ "name", "state", "country", "region" }`. For a city in a country without states, `state` is an empty string.

## Filter a leaderboard by location

Send one location in the `location` array of [`leaderboard.getAccountLeaderboard`](/reference/leaderboards/leaderboard-get-account-leaderboard). Each level needs all the levels above it:

| To filter by | Send |
| --- | --- |
| Region | `region` |
| Country | `region` and `country` |
| State | `region`, `country`, and `state` |
| City | `region`, `country`, `state`, and `city` |

```bash
curl https://api.steamsets.com/v1/leaderboard.getAccountLeaderboard \
  -H "Authorization: Bearer $STEAMSETS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leaderboard": "xp",
    "start": 1,
    "end": 10,
    "location": [{ "region": "Europe", "country": "Germany", "state": "Baden-Wurttemberg" }]
  }'
```

The response has a `location` field with the location that SteamSets matched, including the country code:

```json
"location": [
  { "region": "Europe", "countryName": "Germany", "countryCode": "DE", "stateName": "Baden-Wurttemberg", "cityName": null }
]
```

Names are not case-sensitive, so `germany` and `Germany` give the same result. Use the English names from the files above. Country codes such as `DE` do not work as a filter value.

:::note
- A request can have only one location. More than one gives a `400` response.
- The `app_playtime`, `badge_highest_level`, and `badge_completion_time` leaderboards do not support a location filter.
- A location that does not exist gives a `404` response.
:::

## Read the location of an account

Endpoints that return accounts, for example [`account.getInfo`](/reference/accounts/account-get-info) and the leaderboard endpoints, include the `region`, `country`, and `state` of each account. Each field is an object, or `null` when the Steam profile has no location:

```json
{
  "region": { "name": "Europe" },
  "country": { "name": "Germany", "code": "DE" },
  "state": { "name": "Baden-Wurttemberg" }
}
```

The `name` values are the same names as in the files above, so you can send them back as a leaderboard filter.

## Countries

| Country | Code | Region |
| --- | --- | --- |
| Afghanistan | `AF` | Asia |
| Aland Islands | `AX` | Europe |
| Albania | `AL` | Europe |
| Algeria | `DZ` | Africa |
| American Samoa | `AS` | Oceania |
| Andorra | `AD` | Europe |
| Angola | `AO` | Africa |
| Anguilla | `AI` | Americas |
| Antarctica | `AQ` | Antarctic |
| Antigua & Barbuda | `AG` | Americas |
| Argentina | `AR` | Americas |
| Armenia | `AM` | Asia |
| Aruba | `AW` | Americas |
| Australia | `AU` | Oceania |
| Austria | `AT` | Europe |
| Azerbaijan | `AZ` | Asia |
| Bahamas | `BS` | Americas |
| Bahrain | `BH` | Asia |
| Bangladesh | `BD` | Asia |
| Barbados | `BB` | Americas |
| Belarus | `BY` | Europe |
| Belgium | `BE` | Europe |
| Belize | `BZ` | Americas |
| Benin | `BJ` | Africa |
| Bermuda | `BM` | Americas |
| Bhutan | `BT` | Asia |
| Bolivia | `BO` | Americas |
| Bonaire, Sint Eustatius and Saba | `BQ` | Americas |
| Bosnia and Herzegovina | `BA` | Europe |
| Botswana | `BW` | Africa |
| Bouvet Island | `BV` | Antarctic |
| Brazil | `BR` | Americas |
| British Indian Ocean Territory | `IO` | Africa |
| British Virgin Islands | `VG` | Americas |
| Brunei Darussalam | `BN` | Asia |
| Bulgaria | `BG` | Europe |
| Burkina Faso | `BF` | Africa |
| Burundi | `BI` | Africa |
| Cambodia | `KH` | Asia |
| Cameroon | `CM` | Africa |
| Canada | `CA` | Americas |
| Cape Verde | `CV` | Africa |
| Cayman Islands | `KY` | Americas |
| Central African Republic | `CF` | Africa |
| Chad | `TD` | Africa |
| Chile | `CL` | Americas |
| China | `CN` | Asia |
| Christmas Island | `CX` | Oceania |
| Cocos (Keeling) Islands | `CC` | Oceania |
| Colombia | `CO` | Americas |
| Comoros | `KM` | Africa |
| Congo | `CG` | Africa |
| Congo, the Democratic Republic of the | `CD` | Africa |
| Cook Islands | `CK` | Oceania |
| Costa Rica | `CR` | Americas |
| Cote D'ivoire (Ivory Coast) | `CI` | Africa |
| Croatia | `HR` | Europe |
| Cuba | `CU` | Americas |
| Curacao | `CW` | Americas |
| Cyprus | `CY` | Europe |
| Czech Republic | `CZ` | Europe |
| Denmark | `DK` | Europe |
| Djibouti | `DJ` | Africa |
| Dominica | `DM` | Americas |
| Dominican Republic | `DO` | Americas |
| Ecuador | `EC` | Americas |
| Egypt | `EG` | Africa |
| El Salvador | `SV` | Americas |
| Equatorial Guinea | `GQ` | Africa |
| Eritrea | `ER` | Africa |
| Estonia | `EE` | Europe |
| Ethiopia | `ET` | Africa |
| Falkland Islands (Malvinas) | `FK` | Americas |
| Faroe Islands | `FO` | Europe |
| Fiji | `FJ` | Oceania |
| Finland | `FI` | Europe |
| France | `FR` | Europe |
| French Guiana | `GF` | Americas |
| French Polynesia | `PF` | Oceania |
| French Southern Territories | `TF` | Antarctic |
| Gabon | `GA` | Africa |
| Gambia | `GM` | Africa |
| Georgia | `GE` | Asia |
| Germany | `DE` | Europe |
| Ghana | `GH` | Africa |
| Gibraltar | `GI` | Europe |
| Greece | `GR` | Europe |
| Greenland | `GL` | Americas |
| Grenada | `GD` | Americas |
| Guadeloupe | `GP` | Americas |
| Guam | `GU` | Oceania |
| Guatemala | `GT` | Americas |
| Guernsey | `GG` | Europe |
| Guinea | `GN` | Africa |
| Guinea-Bissau | `GW` | Africa |
| Guyana | `GY` | Americas |
| Haiti | `HT` | Americas |
| Heard & McDonald Islands | `HM` | Antarctic |
| Honduras | `HN` | Americas |
| Hong Kong | `HK` | Asia |
| Hungary | `HU` | Europe |
| Iceland | `IS` | Europe |
| India | `IN` | Asia |
| Indonesia | `ID` | Asia |
| Iraq | `IQ` | Asia |
| Ireland | `IE` | Europe |
| Islamic Republic of Iran | `IR` | Asia |
| Isle of Man | `IM` | Europe |
| Israel | `IL` | Asia |
| Italy | `IT` | Europe |
| Jamaica | `JM` | Americas |
| Japan | `JP` | Asia |
| Jersey | `JE` | Europe |
| Jordan | `JO` | Asia |
| Kazakhstan | `KZ` | Asia |
| Kenya | `KE` | Africa |
| Kiribati | `KI` | Oceania |
| Korea, Democratic People's Republic of | `KP` | Asia |
| Korea, Republic of | `KR` | Asia |
| Kosovo | `XK` | Europe |
| Kuwait | `KW` | Asia |
| Kyrgyzstan | `KG` | Asia |
| Laos | `LA` | Asia |
| Latvia | `LV` | Europe |
| Lebanon | `LB` | Asia |
| Lesotho | `LS` | Africa |
| Liberia | `LR` | Africa |
| Libya | `LY` | Africa |
| Liechtenstein | `LI` | Europe |
| Lithuania | `LT` | Europe |
| Luxembourg | `LU` | Europe |
| Macau | `MO` | Asia |
| Macedonia, The Former Yugoslav Republic of | `MK` | Europe |
| Madagascar | `MG` | Africa |
| Malawi | `MW` | Africa |
| Malaysia | `MY` | Asia |
| Maldives | `MV` | Asia |
| Mali | `ML` | Africa |
| Malta | `MT` | Europe |
| Marshall Islands | `MH` | Oceania |
| Martinique | `MQ` | Americas |
| Mauritania | `MR` | Africa |
| Mauritius | `MU` | Africa |
| Mayotte | `YT` | Africa |
| Mexico | `MX` | Americas |
| Micronesia | `FM` | Oceania |
| Moldova, Republic of  | `MD` | Europe |
| Monaco | `MC` | Europe |
| Mongolia | `MN` | Asia |
| Monserrat | `MS` | Americas |
| Montenegro | `ME` | Europe |
| Morocco | `MA` | Africa |
| Mozambique | `MZ` | Africa |
| Myanmar | `MM` | Asia |
| Namibia | `NA` | Africa |
| Nauru | `NR` | Oceania |
| Nepal | `NP` | Asia |
| Netherlands | `NL` | Europe |
| New Caledonia | `NC` | Oceania |
| New Zealand | `NZ` | Oceania |
| Nicaragua | `NI` | Americas |
| Niger | `NE` | Africa |
| Nigeria | `NG` | Africa |
| Niue | `NU` | Oceania |
| Norfolk Island | `NF` | Oceania |
| Northern Mariana Islands | `MP` | Oceania |
| Norway | `NO` | Europe |
| Oman | `OM` | Asia |
| Pakistan | `PK` | Asia |
| Palau | `PW` | Oceania |
| Palestinian Territory, Occupied | `PS` | Asia |
| Panama | `PA` | Americas |
| Papua New Guinea | `PG` | Oceania |
| Paraguay | `PY` | Americas |
| Peru | `PE` | Americas |
| Philippines | `PH` | Asia |
| Pitcairn | `PN` | Oceania |
| Poland | `PL` | Europe |
| Portugal | `PT` | Europe |
| Puerto Rico | `PR` | Americas |
| Qatar | `QA` | Asia |
| Reunion | `RE` | Africa |
| Romania | `RO` | Europe |
| Russian Federation | `RU` | Europe |
| Rwanda | `RW` | Africa |
| Saint Barthelemy | `BL` | Americas |
| Saint Lucia | `LC` | Americas |
| Saint Martin (French part) | `MF` | Americas |
| Samoa | `WS` | Oceania |
| San Marino | `SM` | Europe |
| Sao Tome & Principe | `ST` | Africa |
| Saudi Arabia | `SA` | Asia |
| Senegal | `SN` | Africa |
| Serbia | `RS` | Europe |
| Seychelles | `SC` | Africa |
| Sierra Leone | `SL` | Africa |
| Singapore | `SG` | Asia |
| Sint Maarten (Dutch part) | `SX` | Americas |
| Slovakia | `SK` | Europe |
| Slovenia | `SI` | Europe |
| Solomon Islands | `SB` | Oceania |
| Somalia | `SO` | Africa |
| South Africa | `ZA` | Africa |
| South Georgia and the South Sandwich Islands | `GS` | Antarctic |
| South Sudan | `SS` | Africa |
| Spain | `ES` | Europe |
| Sri Lanka | `LK` | Asia |
| St. Helena | `SH` | Africa |
| St. Kitts and Nevis | `KN` | Americas |
| St. Pierre & Miquelon | `PM` | Americas |
| St. Vincent & the Grenadines | `VC` | Americas |
| Sudan | `SD` | Africa |
| Suriname | `SR` | Americas |
| Svalbard & Jan Mayen Islands | `SJ` | Europe |
| Swaziland | `SZ` | Africa |
| Sweden | `SE` | Europe |
| Switzerland | `CH` | Europe |
| Syrian Arab Republic | `SY` | Asia |
| Taiwan | `TW` | Asia |
| Tajikistan | `TJ` | Asia |
| Tanzania, United Republic of | `TZ` | Africa |
| Thailand | `TH` | Asia |
| Timor-Leste | `TL` | Asia |
| Togo | `TG` | Africa |
| Tokelau | `TK` | Oceania |
| Tonga | `TO` | Oceania |
| Trinidad & Tobago | `TT` | Americas |
| Tunisia | `TN` | Africa |
| Turkey | `TR` | Asia |
| Turkmenistan | `TM` | Asia |
| Turks & Caicos Islands | `TC` | Americas |
| Tuvalu | `TV` | Oceania |
| Uganda | `UG` | Africa |
| Ukraine | `UA` | Europe |
| United Arab Emirates | `AE` | Asia |
| United Kingdom (Great Britain) | `GB` | Europe |
| United States | `US` | Americas |
| United States Minor Outlying | `UM` | Americas |
| United States Virgin Islands | `VI` | Americas |
| Uruguay | `UY` | Americas |
| Uzbekistan | `UZ` | Asia |
| Vanuatu | `VU` | Oceania |
| Vatican City State (Holy See) | `VA` | Europe |
| Venezuela | `VE` | Americas |
| Viet Nam | `VN` | Asia |
| Wallis & Futuna Islands | `WF` | Oceania |
| Western Sahara | `EH` | Africa |
| Yemen | `YE` | Asia |
| Zambia | `ZM` | Africa |
| Zimbabwe | `ZW` | Africa |

---

# Quickstart
Source: https://docs.steamsets.com/quickstart

1. **Sign in to SteamSets**

    Go to [steamsets.com](https://steamsets.com) and sign in with your Steam account.

2. **Create a developer app**

    Open [Settings, API keys](https://steamsets.com/settings/api-keys) and create a developer app. SteamSets shows the API key one time only. Copy it and keep it in a secret store or an environment variable.

3. **Send a request**

    Put the key in the `Authorization` header and call an endpoint. This request gets the profile of an account by its SteamID64.

```bash cURL
export STEAMSETS_API_KEY="your-key"

curl https://api.steamsets.com/v1/account.getInfo \
  -H "Authorization: Bearer $STEAMSETS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": {"steamId64": "76561199176433616"}}'
```

```ts TypeScript
import { SteamSets } from '@steamsets/client-ts';

const steamsets = new SteamSets({ token: process.env.STEAMSETS_API_KEY });

const account = await steamsets.account.getInfo({
  id: { steamId64: '76561199176433616' }
});

console.log(account);
```

```python Python
import os
import requests

response = requests.post(
    "https://api.steamsets.com/v1/account.getInfo",
    headers={"Authorization": f"Bearer {os.environ['STEAMSETS_API_KEY']}"},
    json={"id": {"steamId64": "76561199176433616"}},
)
response.raise_for_status()
print(response.json())
```

## Find an account

Endpoints that take an account accept one of these identifiers:

| Field | Example | Description |
| --- | --- | --- |
| `id.steamId64` | `"76561199176433616"` | The 17-digit SteamID64, as a string. |
| `id.accountId` | `1216167888` | The 32-bit Steam account ID. |
| `vanity` | `{"type": "steam", "value": "webx"}` | The custom URL name of the Steam profile. |

## Next steps

**[Authentication](/authentication)**

Keep your key safe and rotate it.

**[Errors](/errors)**

Read the problem details the API returns.

---

# Rate limits
Source: https://docs.steamsets.com/rate-limits

The API limits how many requests each API key can send in a time window. Each response tells you your current limit in these headers:

| Header | Description |
| --- | --- |
| `x-ratelimit-limit` | The number of requests you can send in the current window. |
| `x-ratelimit-remaining` | The number of requests that are left in the current window. |
| `x-ratelimit-reset` | The time when the window resets. |

When `x-ratelimit-remaining` is `0`, the next request gets a `429 Too Many Requests` response. Wait until `x-ratelimit-reset`, then send the request again.

## Send fewer requests

- Cache responses. Most profile and badge data changes a few times a day, not every second.
- Use the list endpoints with pagination, not one request for each item.
- For live data, subscribe to a stream such as `activity.streamGlobalFeed` or `stats.subscribe`, and do not poll.

## Queue endpoints

Endpoints such as `account.queueUpdate` start a background refresh from Steam. The refresh can take some time, so do not send the request again for the same account while a refresh is in progress.

---

# SteamSets API
Source: https://docs.steamsets.com/reference

Version 1.0.0

Base URL: `https://api.steamsets.com`

## Accounts

Steam profiles, badge collections, friends, and owned apps.

- [`POST /v1/account.compareBadges`](/reference/accounts/compare-badges) — Compare badge collections between accounts.
- [`POST /v1/account.findFriendPath`](/reference/accounts/account-find-friend-path) — Find up to N shortest friend paths between two accounts.
- [`POST /v1/account.getBadgeHeatmap`](/reference/accounts/account-get-badge-heatmap) — Get monthly badge crafting counts for an account.
- [`POST /v1/account.getBadgeStats`](/reference/accounts/account-get-badge-stats) — Get account badge statistics.
- [`POST /v1/account.getDataPoints`](/reference/accounts/account-get-data-points) — Get account data points for charts.
- [`POST /v1/account.getInfo`](/reference/accounts/account-get-info) — Get account profile information.
- [`POST /v1/account.getTrending`](/reference/accounts/account-get-trending) — Top accounts by unique viewers in a window.
- [`POST /v1/account.getViewStats`](/reference/accounts/get-view-stats) — Get profile view counts (24h/7d/30d × unique/total) for an account.
- [`POST /v1/account.listApps`](/reference/accounts/account-list-apps) — List account owned apps.
- [`POST /v1/account.listBadges`](/reference/accounts/account-list-badges) — List account badges.
- [`POST /v1/account.listCraftedLevels`](/reference/accounts/account-list-crafted-levels) — List crafted badge levels.
- [`POST /v1/account.listFriends`](/reference/accounts/account-list-friends) — List account friends.
- [`POST /v1/account.listInventorySets`](/reference/accounts/account-list-inventory-sets) — List inventory sets.
- [`POST /v1/account.listLeaderboardHistory`](/reference/accounts/account-list-leaderboard-history) — Get leaderboard history.
- [`POST /v1/account.listOwnedBadges`](/reference/accounts/account-list-owned-badges) — List owned badges.
- [`POST /v1/account.listOwnedGroups`](/reference/accounts/account-list-owned-groups) — List groups owned by account.
- [`POST /v1/account.queueUpdate`](/reference/accounts/account-queue-update) — Queue account update.
- [`POST /v1/account.refreshInventory`](/reference/accounts/account-refresh-inventory) — Refresh inventory.
- [`POST /v1/account.refreshSession`](/reference/accounts/account-refresh-session) — Refresh session token.
- [`GET /v1/account.subscribe`](/reference/accounts/account-subscribe) — Server-sent-events stream of per-account updates (queue status, view ticks, update progress).
- [`POST /v1/account.updateProgress`](/reference/accounts/account-update-progress) — Get the live progress of an account's most recent update.

## Badges

Steam badges, their tags, and the accounts that crafted them.

- [`POST /v1/badge.getTags`](/reference/badges/badge-get-tags) — Get a badge's tags for editing.
- [`POST /v1/badge.listCrafters`](/reference/badges/badge-list-crafters) — List accounts that own a badge (earliest completion first). Donator perk — page size scales with Patreon tier.
- [`POST /v1/badge.listTags`](/reference/badges/badge-list-tags) — List badge tags.
- [`GET /v1/badge.pricing.subscribe`](/reference/badges/badge-pricing-subscribe) — Server-sent-events stream of badge pricing ticks. Forwards every tick — filter client-side.
- [`POST /v1/badge.setTags`](/reference/badges/badge-set-tags) — Replace a badge's tags.

## Apps

Steam apps (games), their badges, and the accounts that own them.

- [`POST /v1/app.listBadges`](/reference/apps/app-list-badges) — List app badges.
- [`POST /v1/app.listOwners`](/reference/apps/app-list-owners) — List accounts that own an app (highest playtime first). Donator perk — page size scales with Patreon tier.

## Items

Owners of trading cards and booster packs.

- [`POST /v1/item.findOwners`](/reference/items/item-find-owners) — Find owners of one or more trading cards or booster packs. Friend paths from the requester are included for logged-in callers.
- [`POST /v1/item.findSpareHolders`](/reference/items/item-find-spare-holders) — Find accounts with a spare copy of one or more trading cards: a copy their badge does not need. Only cards with few owners are looked up. Every caller gets the totals. A donator gets the holders, nearest in the friend graph first.
- [`POST /v1/item.findWanters`](/reference/items/item-find-wanters) — Find accounts that want one or more trading cards: they watch the card, have it on their wishlist, or need it to finish a set they almost have, and do not own it. Every caller gets the totals. A donator gets the wanters, nearest in the friend graph first.

## Leaderboards

Account and group rankings, and how they change over time.

- [`POST /v1/leaderboard.getAccountLeaderboard`](/reference/leaderboards/leaderboard-get-account-leaderboard) — Get account leaderboard.
- [`POST /v1/leaderboard.getBucketLeaders`](/reference/leaderboards/leaderboard-get-bucket-leaders) — Get the top account in each value bucket.
- [`POST /v1/leaderboard.getChanges`](/reference/leaderboards/get-changes) — Top movers in a windowed delta on a leaderboard.
- [`POST /v1/leaderboard.getGroupLeaderboard`](/reference/leaderboards/leaderboard-get-group-leaderboard) — Get group leaderboard.
- [`POST /v1/leaderboard.getLowestRanks`](/reference/leaderboards/leaderboard-get-lowest-ranks) — Get lowest ranked accounts.
- [`POST /v1/leaderboard.listBadges`](/reference/leaderboards/leaderboard-list-badges) — List leaderboard badges.
- [`POST /v1/leaderboard.previewAccountRank`](/reference/leaderboards/leaderboard-preview-account-rank) — Preview account rank.

## Activity

The activity feed of one account or of all of SteamSets.

- [`POST /v1/activity.listAccountFeed`](/reference/activity/list-account-feed) — List the activity feed for a single account (profile timeline).
- [`POST /v1/activity.listGlobalFeed`](/reference/activity/list-global-feed) — List the global activity feed.
- [`GET /v1/activity.streamGlobalFeed`](/reference/activity/stream-global-feed) — Live server-sent-events stream of the global activity feed.

## Stats

Platform statistics, as a snapshot or as a live stream.

- [`POST /v1/stats.getStats`](/reference/stats/stats-get-stats) — Get platform statistics.
- [`GET /v1/stats.subscribe`](/reference/stats/stats-subscribe) — Server-sent-events stream of platform stats. Emits a snapshot, then deltas as the queues commit them.

## Search

What people search for on SteamSets.

- [`POST /v1/search.getTrending`](/reference/search/search-get-trending) — Top search queries in a window, by unique searcher count.

## Site

Site-wide broadcasts as a live stream.

- [`GET /v1/site.subscribe`](/reference/site/site-subscribe) — Server-sent-events stream of site-wide broadcasts (maintenance, announcements, etc).

## Donations

Progress toward the monthly donation goal.

- [`POST /v1/donate.getGoal`](/reference/donations/donate-get-goal) — Get this month's donation goal progress.

## roles

- [`POST /v1/roles.listCustom`](/reference/roles/roles-list-custom) — List custom roles.

---

# Find up to N shortest friend paths between two accounts
Source: https://docs.steamsets.com/reference/accounts/account-find-friend-path

`POST /v1/account.findFriendPath`

---

# Get monthly badge crafting counts for an account
Source: https://docs.steamsets.com/reference/accounts/account-get-badge-heatmap

`POST /v1/account.getBadgeHeatmap`

---

# Get account badge statistics
Source: https://docs.steamsets.com/reference/accounts/account-get-badge-stats

`POST /v1/account.getBadgeStats`

---

# Get account data points for charts
Source: https://docs.steamsets.com/reference/accounts/account-get-data-points

`POST /v1/account.getDataPoints`

---

# Get account profile information
Source: https://docs.steamsets.com/reference/accounts/account-get-info

`POST /v1/account.getInfo`

---

# Top accounts by unique viewers in a window
Source: https://docs.steamsets.com/reference/accounts/account-get-trending

`POST /v1/account.getTrending`

---

# List account owned apps
Source: https://docs.steamsets.com/reference/accounts/account-list-apps

`POST /v1/account.listApps`

---

# List account badges
Source: https://docs.steamsets.com/reference/accounts/account-list-badges

`POST /v1/account.listBadges`

---

# List crafted badge levels
Source: https://docs.steamsets.com/reference/accounts/account-list-crafted-levels

`POST /v1/account.listCraftedLevels`

---

# List account friends
Source: https://docs.steamsets.com/reference/accounts/account-list-friends

`POST /v1/account.listFriends`

---

# List inventory sets
Source: https://docs.steamsets.com/reference/accounts/account-list-inventory-sets

Get all trading card sets with ownership information for the authenticated user

`POST /v1/account.listInventorySets`

---

# Get leaderboard history
Source: https://docs.steamsets.com/reference/accounts/account-list-leaderboard-history

`POST /v1/account.listLeaderboardHistory`

---

# List owned badges
Source: https://docs.steamsets.com/reference/accounts/account-list-owned-badges

`POST /v1/account.listOwnedBadges`

---

# List groups owned by account
Source: https://docs.steamsets.com/reference/accounts/account-list-owned-groups

`POST /v1/account.listOwnedGroups`

---

# Queue account update
Source: https://docs.steamsets.com/reference/accounts/account-queue-update

`POST /v1/account.queueUpdate`

---

# Refresh inventory
Source: https://docs.steamsets.com/reference/accounts/account-refresh-inventory

Trigger a refresh of the authenticated user's Steam inventory. Rate limited based on account tier.

`POST /v1/account.refreshInventory`

---

# Refresh session token
Source: https://docs.steamsets.com/reference/accounts/account-refresh-session

`POST /v1/account.refreshSession`

---

# Server-sent-events stream of per-account updates (queue status, view ticks, update progress).
Source: https://docs.steamsets.com/reference/accounts/account-subscribe

`GET /v1/account.subscribe`

---

# Get the live progress of an account's most recent update.
Source: https://docs.steamsets.com/reference/accounts/account-update-progress

`POST /v1/account.updateProgress`

---

# Compare badge collections between accounts
Source: https://docs.steamsets.com/reference/accounts/compare-badges

`POST /v1/account.compareBadges`

---

# Get profile view counts (24h/7d/30d × unique/total) for an account
Source: https://docs.steamsets.com/reference/accounts/get-view-stats

`POST /v1/account.getViewStats`

---

# List the activity feed for a single account (profile timeline)
Source: https://docs.steamsets.com/reference/activity/list-account-feed

`POST /v1/activity.listAccountFeed`

---

# List the global activity feed
Source: https://docs.steamsets.com/reference/activity/list-global-feed

`POST /v1/activity.listGlobalFeed`

---

# Live server-sent-events stream of the global activity feed
Source: https://docs.steamsets.com/reference/activity/stream-global-feed

`GET /v1/activity.streamGlobalFeed`

---

# List app badges
Source: https://docs.steamsets.com/reference/apps/app-list-badges

`POST /v1/app.listBadges`

---

# List accounts that own an app (highest playtime first). Donator perk — page size scales with Patreon tier.
Source: https://docs.steamsets.com/reference/apps/app-list-owners

`POST /v1/app.listOwners`

---

# Get a badge's tags for editing
Source: https://docs.steamsets.com/reference/badges/badge-get-tags

`POST /v1/badge.getTags`

---

# List accounts that own a badge (earliest completion first). Donator perk — page size scales with Patreon tier.
Source: https://docs.steamsets.com/reference/badges/badge-list-crafters

`POST /v1/badge.listCrafters`

---

# List badge tags
Source: https://docs.steamsets.com/reference/badges/badge-list-tags

`POST /v1/badge.listTags`

---

# Server-sent-events stream of badge pricing ticks. Forwards every tick — filter client-side.
Source: https://docs.steamsets.com/reference/badges/badge-pricing-subscribe

`GET /v1/badge.pricing.subscribe`

---

# Replace a badge's tags
Source: https://docs.steamsets.com/reference/badges/badge-set-tags

`POST /v1/badge.setTags`

---

# Get this month's donation goal progress
Source: https://docs.steamsets.com/reference/donations/donate-get-goal

Public — no auth required. Aggregated per calendar month (UTC). Each supporter carries their own total for the month.

`POST /v1/donate.getGoal`

---

# Find owners of one or more trading cards or booster packs. Friend paths from the requester are included for logged-in callers.
Source: https://docs.steamsets.com/reference/items/item-find-owners

`POST /v1/item.findOwners`

---

# Find accounts with a spare copy of one or more trading cards: a copy their badge does not need. Only cards with few owners are looked up. Every caller gets the totals. A donator gets the holders, nearest in the friend graph first.
Source: https://docs.steamsets.com/reference/items/item-find-spare-holders

`POST /v1/item.findSpareHolders`

---

# Find accounts that want one or more trading cards: they watch the card, have it on their wishlist, or need it to finish a set they almost have, and do not own it. Every caller gets the totals. A donator gets the wanters, nearest in the friend graph first.
Source: https://docs.steamsets.com/reference/items/item-find-wanters

`POST /v1/item.findWanters`

---

# Top movers in a windowed delta on a leaderboard
Source: https://docs.steamsets.com/reference/leaderboards/get-changes

`POST /v1/leaderboard.getChanges`

---

# Get account leaderboard
Source: https://docs.steamsets.com/reference/leaderboards/leaderboard-get-account-leaderboard

`POST /v1/leaderboard.getAccountLeaderboard`

---

# Get the top account in each value bucket
Source: https://docs.steamsets.com/reference/leaderboards/leaderboard-get-bucket-leaders

`POST /v1/leaderboard.getBucketLeaders`

---

# Get group leaderboard
Source: https://docs.steamsets.com/reference/leaderboards/leaderboard-get-group-leaderboard

`POST /v1/leaderboard.getGroupLeaderboard`

---

# Get lowest ranked accounts
Source: https://docs.steamsets.com/reference/leaderboards/leaderboard-get-lowest-ranks

`POST /v1/leaderboard.getLowestRanks`

---

# List leaderboard badges
Source: https://docs.steamsets.com/reference/leaderboards/leaderboard-list-badges

`POST /v1/leaderboard.listBadges`

---

# Preview account rank
Source: https://docs.steamsets.com/reference/leaderboards/leaderboard-preview-account-rank

`POST /v1/leaderboard.previewAccountRank`

---

# List custom roles
Source: https://docs.steamsets.com/reference/roles/roles-list-custom

Returns the name, description and icon of every custom role. Built-in roles are not included. Public, no auth required.

`POST /v1/roles.listCustom`

---

# Top search queries in a window, by unique searcher count
Source: https://docs.steamsets.com/reference/search/search-get-trending

`POST /v1/search.getTrending`

---

# Server-sent-events stream of site-wide broadcasts (maintenance, announcements, etc).
Source: https://docs.steamsets.com/reference/site/site-subscribe

`GET /v1/site.subscribe`

---

# Get platform statistics
Source: https://docs.steamsets.com/reference/stats/stats-get-stats

`POST /v1/stats.getStats`

---

# Server-sent-events stream of platform stats. Emits a snapshot, then deltas as the queues commit them.
Source: https://docs.steamsets.com/reference/stats/stats-subscribe

`GET /v1/stats.subscribe`

---

# TypeScript SDK
Source: https://docs.steamsets.com/sdk

`@steamsets/client-ts` is the official TypeScript SDK. We generate it from the same OpenAPI spec as this reference, so each endpoint in the [API reference](/reference) has a method with the same name.

## Install

```package-install
npm install @steamsets/client-ts
```

## Create a client

```ts
import { SteamSets } from '@steamsets/client-ts';

const steamsets = new SteamSets({ token: process.env.STEAMSETS_API_KEY });
```

The endpoint name tells you the method: `account.getInfo` is `steamsets.account.getInfo()`, and `leaderboard.getAccountLeaderboard` is `steamsets.leaderboard.getAccountLeaderboard()`.

## Handle errors

The SDK throws a `SteamSetsError` for each non-`2xx` response. The error has the HTTP response and the raw [problem details](/errors) body.

```ts
import { SteamSetsError } from '@steamsets/client-ts/models/errors';

try {
  await steamsets.account.getInfo({ id: { steamId64: '76561199176433616' } });
} catch (error) {
  if (error instanceof SteamSetsError) {
    console.error(error.httpMeta.response.status, error.httpMeta.body);
  }
  throw error;
}
```

## Other languages

There is no official SDK for other languages yet. The API is plain JSON over HTTPS, so any HTTP client works. Each page in the [API reference](/reference) has cURL and Python samples that you can copy.