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 October 21, 2026
curl --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.
curl --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 is the creation time of the cached inventory snapshot used for this result, not when its items were acquired. The second describes the local 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.
Read snapshot time and quote time as different clocks
Repricing answers what the already observed item rows are worth under saved quotes. It does not check whether Steam still exposes those items or prove current ownership.
| Field | What it measures | What it cannot establish |
|---|---|---|
meta.inventory_created_at | Creation time of the inventory snapshot actually used. Repricing the same snapshot retains that time. | Item acquisition, purchase or trade-completion time, or unchanged present ownership. |
meta.cache_age / meta.cache_ttl | The snapshot age and applicable lifetime at response generation. | That a saved response file is still fresh later. Re-reading a file makes no new Steam observation. |
meta.prices_updated_at | When WOK performed this local repricing operation. | That every marketplace quote was fetched at that instant. |
items[].priceupdatedat | The selected item's saved source-quote timestamp, when available. | The inventory scan time or a completed sale. Another source can have a different timestamp. |
If only quotes are needed, reprice the fresh snapshot locally. If your application needs a new public-item observation, decide explicitly whether to make a normal or cache-bypassing inventory read and pay its usual quota cost. Neither choice recovers private data. Use a client freshness policy appropriate to your workflow; do not present a response's capture time as evidence that ownership remains unchanged.
Price-only valuation rulesSaved item-price observations and gapsDiagnose health, access and data separately
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.
curl --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