Inventory operations and source cost
Steam inventory API caching: fewer repeat scans and safer retries
Reuse a fresh item snapshot, revalue its existing items from WOK's local price catalog and batch independent player-game pairs. Read response metadata so a fast answer never hides how old its inventory is.
Updated September 26, 2026
WOK APIcurl --fail-with-body --max-time 45 --get \
-H "Authorization: Bearer $WOK_API_KEY" \
--data-urlencode "steam_id=$STEAM_ID" \
--data-urlencode "game=cs2" \
--data-urlencode "top=0" \
"https://woksteamapi.com/v1/inventory"Pick the cheapest call that answers the user
A normal inventory request checks WOK's cache first. A successful snapshot has a configurable default lifetime of 1,800 seconds; use meta.cache_age and meta.cache_ttl in the actual response rather than assuming that default in your client.
| User need | Request | Steam / proxy work |
|---|---|---|
| Current cached view is acceptable | Normal GET /v1/inventory | Fresh cache hit avoids another inventory scan; a miss fetches from Steam. |
| Only the valuation should change | GET /v1/inventory?refresh_prices=1 | Reprices a fresh cached snapshot locally without a Steam or proxy request. A missing or expired snapshot returns HTTP 404 inventory_cache_miss. |
| Several player-game pairs | POST /v1/inventories | One client HTTP call schedules bounded independent pairs. Each uncached pair may still need its own Steam fetch. |
| Must bypass cached items | GET /v1/inventory?no_cache=1 | May trigger a fresh upstream read. Reserve this for an explicit freshness requirement. |
Every normal or price-refresh request still consumes a WOK quota unit. A batch reserves one unit for each unique player-game pair, up to 20 SteamIDs, four named games and 80 pairs. Batching reduces client round trips and controls concurrency; it does not turn 80 uncached inventories into one Steam request.
Refresh prices without changing the item snapshot
Run the normal read once. While that item snapshot is still fresh, use price-only mode when your product needs updated valuation. The operation does not extend the inventory lifetime or prove that Steam items are unchanged.
WOK APIcurl --fail-with-body --max-time 35 --get \
-H "Authorization: Bearer $WOK_API_KEY" \
--data-urlencode "steam_id=$STEAM_ID" \
--data-urlencode "game=cs2" \
--data-urlencode "refresh_prices=1" \
--data-urlencode "top=0" \
"https://woksteamapi.com/v1/inventory"Successful output has meta.price_refreshed=true, meta.inventory_created_at and meta.prices_updated_at. The first timestamp describes item ownership freshness; the second describes the repricing operation. Item-level priceupdatedat still reflects each source observation and can be older. Show an unpriced item as unknown, not $0.
On 404 inventory_cache_miss, choose whether the user really needs a new Steam scan. If so, make one normal request. Never combine refresh_prices=1 with no_cache=1; the API rejects that combination.
Revalue several existing snapshots in one call
The batch example is useful for a roster or portfolio already read once. It performs no Steam scan in refresh_prices mode. Each pair has its own result: inspect results[].ok and results[].error.code before using its items.
WOK APIcurl --fail-with-body --max-time 90 \
-H "Authorization: Bearer $WOK_API_KEY" \
-H "Content-Type: application/json" \
--data '{"steamids":["76561198000000001","76561198000000002"],"games":["cs2","rust"],"refresh_prices":true,"top":0}' \
"https://woksteamapi.com/v1/inventories"A pair missing a fresh snapshot reports inventory_cache_miss while other pairs may succeed. Fetch only those missing pairs normally if the application needs them. top=0 includes all grouped item rows; a smaller top only changes response size, not the inventory work or quota units.
Handle 429 and measure whether scans fell
HTTP 429 can come from the WOK key's minute limit or the edge proxy's per-IP limit. For a key limit, use Retry-After when present; the edge response may have no such header, so use capped exponential backoff with jitter. A native inventory response may instead be HTTP 200 with status=limited when Steam capacity is temporary. Avoid bursts of no_cache=1.
Separate status=ok, empty, private, notfound, limited and error. Private and not-found results are not successful zero-valued inventories.
Log meta.cached, meta.cache_age, meta.cache_ttl and meta.upstream_attempts with each response. Compare upstream attempts and paid proxy bytes over matched traffic windows before claiming savings.
Keep request latency, 429 rate and 5xx rate alongside those cost counters. A higher cache-hit share only helps if clients still receive data fresh enough for their actual workflow.
Batch request and response contractDetailed retry policyPrice-source freshness rulesOpenAPI schema