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. Requires exactly one entry in itemIds. A cursor from a 'closest' page continues that order, with or without sort. 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, takes no offset, and pages through that slice with 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:nonerainbowshadowneonshattervaporwavestardustcosmicsakurahalomoltenglassamber_glintamethyst_glintemerald_depthsapphire_depthruby_firediamond_fireastral_skynebula_skystaff_scandeveloper_scancrownlensboost
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_boosterlevels_adminastralnebula
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

supporterSupporterStatus

Whether this account helps cover the monthly server costs, omitted when it never donated

Show properties
activebooleanrequired

Donated this month

monthsinteger<int32>required

Total months with a donation

min 0
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<int64>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

tradeUrlstring

The owner's Steam trade offer link, when the owner added one. Only sent to a logged-in caller

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 'Accept: application/json' \
  -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",
            "supporter": {
              "active": true,
              "months": 3
            },
            "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",
              "supporter": {
                "active": true,
                "months": 3
              },
              "themeColor": "#FF5733",
              "vacBans": 0,
              "xp": 123456
            }
          ],
          "pathFound": true,
          "tradeUrl": "string"
        }
      ],
      "totalOwners": 0
    }
  ]
}