Skip to content
SteamSets
Esc
↑↓navigate↵open⌘Jpreview

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.findOwners
Authorization
AuthorizationBearer token · headerrequired
Request body
requiredapplication/json
cursorstring

Opaque pagination cursor from the previous page's nextCursor. Pages to any depth at constant cost, and requires exactly one entry in itemIds. Omit for the first page.

itemIdsinteger<int64>[] | nullrequired

Trading item class IDs to look up

min items 1 · max items 100
maxDepthinteger<int32>

Friend-path depth limit (default 4, max 6); ignored when not logged in

min 0
offsetinteger<int32>

Number of owners to skip per item, for pagination. Random access, but only one item at a time past owner 100 and never past 10000 — use cursor to page deeper.

min 0
ownersPerIteminteger<int32>

Page size, max owners returned per item (default 10, max 25)

min 0
sortstring

Owner order. 'owned' (default) returns the most copies owned first. 'closest' reranks a wider slice of owners by friend path length, nearest first; it needs a logged-in caller and the first page (no offset, no cursor), and never returns a nextCursor.

Allowed:ownedclosest
Responses
200

OK

itemsItemOwners[] | nullrequired
Show properties
Array of ItemOwners
classIdinteger<int64>required
min 0
nextCursorstring

Pass as cursor to fetch the next page of this item's owners. Absent when there are no more owners or your role's depth limit is reached.

ownersOwner[] | nullrequired
Show properties
Array of Owner
accountLeaderboardAccount | nullrequired

The owning account

Show properties
animatedAvatarstringrequired

The animated avatar of the account

appsinteger<int32>required

The number of apps the account has

min 0
avatarstringrequired

The avatar hash of the account

avatarFramestringrequired

The avatar frame of the account

awardsGiveninteger<int32>required

The number of awards the account has

min 0
awardsReceivedinteger<int32>required

The number of awards the account has

min 0
backgroundstringrequired

The background of the account

badgesinteger<int32>required

The number of badges the account has

min 0
bansinteger<int32>required

The number of bans

min 0
cityLeaderboardCity | null

The city of the account

Show properties
namestringrequired

The name of the city

countryLeaderboardCountry | null

The country of the account

Show properties
codestring

The code of the country

namestringrequired

The name of the country

createdAtstring<date-time>required

The time the account was created

donatedinteger<int32>required

The total of donations the account has

min 0
economyBanstringrequired

The economy ban of the account

foilBadgesinteger<int32>required

The number of foil badges the account has

min 0
friendsinteger<int32>required

The number of friends the account has

min 0
gameBansinteger<int32>required

The number of game bans

min 0
levelinteger<int32>required

The level of the account

min 0
miniBackgroundstringrequired

The mini background of the account

namestringrequired

The name of the account

nameEffectstringrequired

Donator name effect, none when unset or the account no longer holds an entitling role

Allowed:nonerainbowglitchshadowneonretrostampedshattertypewritervaporwavesunken
normalBadgesinteger<int32>required

The number of normal badges the account has

min 0
playtimeinteger<int32>required

The playtime of the account

min 0
pointsGiveninteger<int32>required

The number of points the account has

min 0
pointsReceivedinteger<int32>required

The number of points the account has

min 0
privacystringrequired

The privacy of the account

Allowed:publicprivatefriends_only
regionLeaderboardRegion | null

The region of the account

Show properties
namestringrequired

The name of the region

rolesRole[] | nullrequired

The roles of the account

Show properties
Array of Role
extrasobject | nullrequired

Extra data associated with the role

ratinginteger<int32>required

The higher the more presedence it has

rolestringrequired
Allowed:userdonatorstaffdeveloperpartnerowneramethystamberemeraldsapphirerubydiamondcontributorearly_supporterbetatranslatortop_100badge_scoutnitro_boosterastralnebula
stateLeaderboardState | null

The state of the account

Show properties
namestringrequired

The name of the state

steamIdstringrequired

The steam id

steamSetsScoreinteger<int32>required

The steam sets score

min 0
steamSetsVanitystringrequired

The vanity of the account

steamVanitystringrequired

The vanity of the account

themeColorstring | nullrequired

Donator profile theme color as #RRGGBB (no alpha), null when unset or the account no longer holds an entitling role

vacBansinteger<int32>required

The number of vac bans

min 0
xpinteger<int32>required

The number of xp the account has

min 0
amountinteger<int32>required

Number of copies owned

min 0
assetIdinteger<int32>required

A representative asset id for deep-linking into the owner's inventory (#{appId}{contextId}{assetId})

min 0
distanceinteger<int32>

Number of hops from requester to owner

min 0
pathLeaderboardAccount[] | null

Accounts from requester (first) to owner (last), inclusive

pathFoundbooleanrequired

Whether a friend path was found within maxDepth

totalOwnersinteger<int32>required

Total accounts that own at least one copy of this item

min 0
400

Bad Request

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[] | null

Optional list of individual error details

Show properties
Array of ErrorDetail
locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueany

The value at the given location

instancestring<uri>

A URI reference that identifies the specific occurrence of the problem.

statusinteger<int64>

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring<uri>

A URI reference to human-readable documentation for the error.

default: "about:blank"
422

Unprocessable Entity

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[] | null

Optional list of individual error details

Show properties
Array of ErrorDetail
locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueany

The value at the given location

instancestring<uri>

A URI reference that identifies the specific occurrence of the problem.

statusinteger<int64>

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring<uri>

A URI reference to human-readable documentation for the error.

default: "about:blank"
500

Internal Server Error

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[] | null

Optional list of individual error details

Show properties
Array of ErrorDetail
locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueany

The value at the given location

instancestring<uri>

A URI reference that identifies the specific occurrence of the problem.

statusinteger<int64>

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring<uri>

A URI reference to human-readable documentation for the error.

default: "about:blank"
503

Service Unavailable

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[] | null

Optional list of individual error details

Show properties
Array of ErrorDetail
locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueany

The value at the given location

instancestring<uri>

A URI reference that identifies the specific occurrence of the problem.

statusinteger<int64>

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring<uri>

A URI reference to human-readable documentation for the error.

default: "about:blank"
Try it
Server
Authorization
Bodyapplication/json
Request
curl -X POST 'https://api.steamsets.com/v1/item.findOwners' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "cursor": "string",
  "itemIds": [
    0
  ],
  "maxDepth": 0,
  "offset": 0,
  "ownersPerItem": 0,
  "sort": "owned"
}'
Response
{
  "items": [
    {
      "classId": 0,
      "nextCursor": "string",
      "owners": [
        {
          "account": {
            "animatedAvatar": "string",
            "apps": 123456,
            "avatar": "f1a1d2c3d0c9d1e1f2f3f4f5f6f7f8f9",
            "avatarFrame": "string",
            "awardsGiven": 123456,
            "awardsReceived": 123456,
            "background": "string",
            "badges": 123456,
            "bans": 0,
            "city": {
              "name": "Bad Krozingen"
            },
            "country": {
              "code": "DE",
              "name": "Germany"
            },
            "createdAt": "2023-01-01T00:00:00Z",
            "donated": 123456,
            "economyBan": "steam",
            "foilBadges": 123456,
            "friends": 123456,
            "gameBans": 0,
            "level": 123456,
            "miniBackground": "string",
            "name": "steamsets",
            "nameEffect": "rainbow",
            "normalBadges": 123456,
            "playtime": 123456,
            "pointsGiven": 123456,
            "pointsReceived": 123456,
            "privacy": "public",
            "region": {
              "name": "Europe"
            },
            "roles": [
              {
                "extras": {
                  "property1": null,
                  "property2": null
                },
                "rating": 0,
                "role": "user"
              }
            ],
            "state": {
              "name": "Baden-Wurttemberg"
            },
            "steamId": "76561198842603734",
            "steamSetsScore": 0,
            "steamSetsVanity": "steamsets",
            "steamVanity": "steamsets",
            "themeColor": "#FF5733",
            "vacBans": 0,
            "xp": 123456
          },
          "amount": 0,
          "assetId": 0,
          "distance": 0,
          "path": [
            {
              "animatedAvatar": "string",
              "apps": 123456,
              "avatar": "f1a1d2c3d0c9d1e1f2f3f4f5f6f7f8f9",
              "avatarFrame": "string",
              "awardsGiven": 123456,
              "awardsReceived": 123456,
              "background": "string",
              "badges": 123456,
              "bans": 0,
              "city": {
                "name": "Bad Krozingen"
              },
              "country": {
                "code": "DE",
                "name": "Germany"
              },
              "createdAt": "2023-01-01T00:00:00Z",
              "donated": 123456,
              "economyBan": "steam",
              "foilBadges": 123456,
              "friends": 123456,
              "gameBans": 0,
              "level": 123456,
              "miniBackground": "string",
              "name": "steamsets",
              "nameEffect": "rainbow",
              "normalBadges": 123456,
              "playtime": 123456,
              "pointsGiven": 123456,
              "pointsReceived": 123456,
              "privacy": "public",
              "region": {
                "name": "Europe"
              },
              "roles": [
                {
                  "extras": {
                    "property1": null,
                    "property2": null
                  },
                  "rating": 0,
                  "role": "user"
                }
              ],
              "state": {
                "name": "Baden-Wurttemberg"
              },
              "steamId": "76561198842603734",
              "steamSetsScore": 0,
              "steamSetsVanity": "steamsets",
              "steamVanity": "steamsets",
              "themeColor": "#FF5733",
              "vacBans": 0,
              "xp": 123456
            }
          ],
          "pathFound": true
        }
      ],
      "totalOwners": 0
    }
  ]
}