item

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.

Changed on Oct 15, 2026

post/v1/item.findSpareHolders

Request

Base URL: https://api.steamsets.com
URL: https://api.steamsets.com/v1/item.findSpareHolders
Auth: HTTP bearer

Request body

$schemastring uri

A URL to the JSON Schema for this object.

holdersPerIteminteger

Max holders returned per item (default 10, max 25)

itemIdsinteger[] nullable required

Trading card class IDs to look up

maxDepthinteger

Friend-path depth limit (default 4, max 6)

Example request

{
  "$schema": "https://api.steamsets.com/schemas/FindSpareHoldersRequestBody.json"
}

Response

$schemastring uri

A URL to the JSON Schema for this object.

lockedboolean required

True when the caller's role does not include the holder list. The totals are still returned.

Example response

{
  "$schema": "https://api.steamsets.com/schemas/FindSpareHoldersResponseBody.json",
  "items": [
    {
      "holders": [
        {
          "account": {
            "apps": 123456,
            "avatar": "f1a1d2c3d0c9d1e1f2f3f4f5f6f7f8f9",
            "awardsGiven": 123456,
            "awardsReceived": 123456,
            "badges": 123456,
            "city": {
              "name": "Bad Krozingen"
            },
            "country": {
              "code": "DE",
              "name": "Germany"
            },
            "createdAt": "2023-01-01T00:00:00Z",
            "donated": 123456,
            "economyBan": "steam",
            "foilBadges": 123456,
            "friends": 123456,
            "level": 123456,
            "name": "steamsets",
            "nameEffect": "rainbow",
            "normalBadges": 123456,
            "playtime": 123456,
            "pointsGiven": 123456,
            "pointsReceived": 123456,
            "privacy": "public",
            "region": {
              "name": "Europe"
            },
            "state": {
              "name": "Baden-Wurttemberg"
            },
            "steamId": "76561198842603734",
            "steamSetsVanity": "steamsets",
            "steamVanity": "steamsets",
            "supporter": {
              "active": true,
              "months": 3
            },
            "themeColor": "#FF5733",
            "xp": 123456
          },
          "path": [
            {
              "apps": 123456,
              "avatar": "f1a1d2c3d0c9d1e1f2f3f4f5f6f7f8f9",
              "awardsGiven": 123456,
              "awardsReceived": 123456,
              "badges": 123456,
              "city": {
                "name": "Bad Krozingen"
              },
              "country": {
                "code": "DE",
                "name": "Germany"
              },
              "createdAt": "2023-01-01T00:00:00Z",
              "donated": 123456,
              "economyBan": "steam",
              "foilBadges": 123456,
              "friends": 123456,
              "level": 123456,
              "name": "steamsets",
              "nameEffect": "rainbow",
              "normalBadges": 123456,
              "playtime": 123456,
              "pointsGiven": 123456,
              "pointsReceived": 123456,
              "privacy": "public",
              "region": {
                "name": "Europe"
              },
              "state": {
                "name": "Baden-Wurttemberg"
              },
              "steamId": "76561198842603734",
              "steamSetsVanity": "steamsets",
              "steamVanity": "steamsets",
              "supporter": {
                "active": true,
                "months": 3
              },
              "themeColor": "#FF5733",
              "xp": 123456
            }
          ]
        }
      ]
    }
  ]
}

Changes

Oct 15, 2026708b7ffcfba3 Revision changes
- warning
  added the new amber_glint enum value to the ///// response property for the response status
- warning
  added the new amber_glint enum value to the ////// response property for the response status
- warning
  added the new amethyst_glint enum value to the ///// response property for the response status
- warning
  added the new amethyst_glint enum value to the ////// response property for the response status
- warning
  added the new astral_sky enum value to the ///// response property for the response status
- warning
  added the new astral_sky enum value to the ////// response property for the response status
- warning
  added the new boost enum value to the ///// response property for the response status
- warning
  added the new boost enum value to the ////// response property for the response status
- warning
  added the new cosmic enum value to the ///// response property for the response status
- warning
  added the new cosmic enum value to the ////// response property for the response status
- warning
  added the new crown enum value to the ///// response property for the response status
- warning
  added the new crown enum value to the ////// response property for the response status
- warning
  added the new developer_scan enum value to the ///// response property for the response status
- warning
  added the new developer_scan enum value to the ////// response property for the response status
- warning
  added the new diamond_fire enum value to the ///// response property for the response status
- warning
  added the new diamond_fire enum value to the ////// response property for the response status
- warning
  added the new emerald_depth enum value to the ///// response property for the response status
- warning
  added the new emerald_depth enum value to the ////// response property for the response status
- warning
  added the new glass enum value to the ///// response property for the response status
- warning
  added the new glass enum value to the ////// response property for the response status
- warning
  added the new halo enum value to the ///// response property for the response status
- warning
  added the new halo enum value to the ////// response property for the response status
- warning
  added the new lens enum value to the ///// response property for the response status
- warning
  added the new lens enum value to the ////// response property for the response status
- warning
  added the new molten enum value to the ///// response property for the response status
- warning
  added the new molten enum value to the ////// response property for the response status
- warning
  added the new nebula_sky enum value to the ///// response property for the response status
- warning
  added the new nebula_sky enum value to the ////// response property for the response status
- warning
  added the new ruby_fire enum value to the ///// response property for the response status
- warning
  added the new ruby_fire enum value to the ////// response property for the response status
- warning
  added the new sakura enum value to the ///// response property for the response status
- warning
  added the new sakura enum value to the ////// response property for the response status
- warning
  added the new sapphire_depth enum value to the ///// response property for the response status
- warning
  added the new sapphire_depth enum value to the ////// response property for the response status
- warning
  added the new staff_scan enum value to the ///// response property for the response status
- warning
  added the new staff_scan enum value to the ////// response property for the response status
- warning
  added the new stardust enum value to the ///// response property for the response status
- warning
  added the new stardust enum value to the ////// response property for the response status
- info
  removed the glitch enum value from the ///// response property for the response status
- info
  removed the glitch enum value from the ////// response property for the response status
- info
  removed the retro enum value from the ///// response property for the response status
- info
  removed the retro enum value from the ////// response property for the response status
- info
  removed the stamped enum value from the ///// response property for the response status
- info
  removed the stamped enum value from the ////// response property for the response status
- info
  removed the sunken enum value from the ///// response property for the response status
- info
  removed the sunken enum value from the ////// response property for the response status
- info
  removed the typewriter enum value from the ///// response property for the response status
- info
  removed the typewriter enum value from the ////// response property for the response status
Oct 15, 2026d8a5ef0076cb Revision changes
- info
  endpoint added

Operation history