Hourly price history
Implemented in the local API. Production deployment and historical coverage are separate release checks; do not assume that every item already has a full series.
Read a chart series
Section titled “Read a chart series”GET /v1/items/{item_id}/history/hourly reads our persisted hourly frames, never
the upstream service. Resolve the exact item ID first; phases and wear are distinct.
curl 'https://api.csfolder.com/v1/items/123/history/hourly?from=2026-09-01&to=2026-09-07&provider=steam&side=ask&limit=100' \ -H "Authorization: Bearer $CSFOLDER_API_KEY"123 is a placeholder. Keep credentials in the server environment, not prompts,
URLs or browser code. See keys and access.
side:askby default, orbid; there is no fallback between them.provider: optional exact market slug. Omit it for every quoted market on the selected side. A selected missing provider never falls back to another market.from/to: inclusive UTC calendar dates, at most 31 days. Default: today and the preceding 30 days. Split all-time retrieval into bounded windows.limit: rows, not hours; default 500, maximum 1,000. MCP defaults to 25/max 100.after: usemeta.next_pageuntil null. Keep item, side, provider and dates unchanged. The cursor remembers omitted selection filters and resolved dates.
Each row contains ts, provider, side, amount, quantity, currency: USD,
minor_units: 2, kind: hourly_cached_quote, availability, ingested_at,
checked_at, and source_observed_at. Amounts are integer USD cents; unknown
quantities are null. Rows sort by UTC bucket and provider, with missing-provider
markers first. The route remains available for identities with stored history
even if they have been removed from the current catalog.
Missing is not zero
Section titled “Missing is not zero”availability |
Meaning |
|---|---|
quoted |
Stored price exists for this provider and side. |
item_missing |
A frame was recorded, but this exact item/phase was absent from its feed. Amount is null. |
no_quote |
Item was present, but there was no quote for the selection. Amount is null. |
Without a provider filter, available providers are returned individually; if none exist on the selected side, one null-provider marker is returned. Omitted providers are not individually enumerated as missing. With a provider filter, missing rows retain the requested provider name.
An hour without a recorded frame has no row, not a zero or a copied prior price. Keep gaps visible in charts. Empty history is not proof that an item was worthless.
What the clocks mean
Section titled “What the clocks mean”ts is the hourly bucket. checked_at is our successful GET/304 verification time;
ingested_at is mirror publication time. source_observed_at is null when the feed
does not provide a real quote timestamp. A 304 can confirm unchanged cached prices
without representing a new marketplace tick. These are neither sales nor OHLC.
Only the first successful verified frame per UTC hour is saved. Later refreshes
within that hour do not overwrite it. Frames are immutable, but pagination is not
a frozen export: a late insertion may require rereading the affected window and
deduplicating by item ID, ts, provider and side. Daily history at /history
remains a separate dataset; it is not expanded into hourly observations.
Build with AI
Section titled “Build with AI”The SDK uses api.request('getHourlyPriceHistory', { params, query }) and bounded
api.pages('getHourlyPriceHistory', input, { maxPages }). The MCP tool has the same
name and argument structure, fetching one page per call. Inspect next_page even
when a page budget is reached: remaining data has not been downloaded.
Ask your agent: “Build a Steam ask chart for this exact item using getHourlyPriceHistory. Preserve null prices and missing hours, show cache check time separately from source time, keep the key server-side and test pagination and 429.”
See TypeScript SDK and MCP and skill.