POST /v1/archive/history

本页内容

POST /v1/archive/history
访问
支持的间隔
支持的来源
请求
参数
响应
响应字段
分桶
错误

返回 BUFF、Youpin、C5Game 和 aggregate 序列的长期挂单价格历史。数据始于 2023 年，每天约更新 1-2 次。每次请求最多 100 个饰品。

在每个分桶内，价格、挂单数量和 total_supply 均为最后观测值。hourly_volume 是近似成交数量：1h 响应中为每小时估算值，1d 分桶中为当天各小时估算值之和。

访问#

需要 Scale 或 Enterprise API 密钥。

支持的间隔#

间隔	分桶
`1h`	小时归档分桶
`1d`	日归档分桶

支持的来源#

来源	字段
`aggregate`	`ask`, `bid`, `ask_volume`, `bid_volume`, `hourly_volume`, `total_supply`
`buff`	`ask`, `bid`, `ask_volume`, `bid_volume`
`youpin`	`ask`, `bid`, `ask_volume`, `bid_volume`
`c5game`	`ask`, `bid`, `ask_volume`, `bid_volume`

默认仅返回 aggregate。

请求#

POSTapi.cs2.sh/v1/archive/history

curl -X POST https://api.cs2.sh/v1/archive/history \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Accept-Encoding: gzip" --compressed \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    "USP-S | Printstream (Factory New)"
  ],
  "start": "2024-01-01",
  "end": "2026-08-23",
  "sources": [
    "aggregate",
    "buff"
  ],
  "interval": "1d",
  "currency": "USD"
}'

参数#

字段	类型	必需	描述
`items`	`string[]`	是	`market_hash_name` 值列表（最多 100 个）。
`start`	`string`	是	开始日期/时间（YYYY-MM-DD 或 RFC3339），包含。
`end`	`string`	否	结束日期/时间（YYYY-MM-DD 或 RFC3339），不含。默认现在。
`sources`	`string[]`	否	筛选特定来源。默认仅 `aggregate`。
`interval`	`string`	否	默认值: `1d`. 允许值: `1h`, `1d`. 分桶间隔。
`currency`	`string`	否	默认值: `USD`. 允许值: `AUD`, `CAD`, `CHF`, `CNY`, `EUR`, `GBP`, `JPY`, `NZD`, `SGD`, `USD`. 响应中所有价格使用的货币。

响应#

{
  "response_time": "2026-08-23T22:00:07.79126838Z",
  "currency": "USD",
  "start": "2026-05-25T00:00:00Z",
  "end": "2026-08-22T00:00:00Z",
  "interval": "1d",
  "items": {
    "USP-S | Printstream (Factory New)": {
      "market_hash_name": "USP-S | Printstream (Factory New)",
      "count": 89,
      "data": [
        {
          "bucket": "2026-05-25T00:00:00Z",
          "aggregate": {
            "time": "2026-05-25T23:59:08Z",
            "ask": 100.66,
            "ask_volume": 1450,
            "bid": 98.45,
            "bid_volume": 126,
            "hourly_volume": 62,
            "total_supply": 31551,
            "sample_count": 24
          },
          "buff": {
            "time": "2026-05-25T23:53:08Z",
            "ask": 101.4,
            "ask_volume": 450,
            "bid": 97.13,
            "bid_volume": 28,
            "sample_count": 24
          },
          "youpin": {
            "time": "2026-05-25T23:59:07Z",
            "ask": 100.66,
            "ask_volume": 574,
            "bid": 98.45,
            "bid_volume": 71,
            "sample_count": 25
          },
          "c5game": {
            "time": "2026-05-25T23:59:07Z",
            "ask": 105.22,
            "ask_volume": 186,
            "bid": 114.79,
            "bid_volume": 26,
            "sample_count": 25
          }
        }
      ]
    }
  }
}

响应字段#

ArchiveHistoryResponse 字段:

字段	类型	必需	描述
`response_time`	`string (date-time)`	是	响应生成时间。
`currency`	`string`	是	响应中所有价格的货币代码：即请求的 `currency`，默认为 `USD`。
`start`	`string (date-time)`	是	查询区间的有效起点，向下对齐到间隔边界。包含。
`end`	`string (date-time)`	是	查询区间的有效终点，向上对齐到间隔边界。不含。
`interval`	`string`	是	允许值: `1h`, `1d`. 请求的分桶间隔。
`items`	`Record<string, ArchiveHistoryItem>`	是	`market_hash_name` 到归档时间序列的映射。
`errors`	ItemError[]	否	与成功结果一起返回的逐饰品失败（部分成功）。

分桶#

字段	描述
`items.<name>.count`	有数据的分桶数。
`items.<name>.data[]`	归档分桶。
`data[].bucket`	分桶边界。
`data[].<platform>`	最后观测的 `ask`/`bid` 和 `ask_volume`/`bid_volume`，附带 `time` 和 `sample_count`。平台：`aggregate`、`buff`、`youpin`、`c5game`。
`data[].aggregate.hourly_volume`	该分桶内的大致成交数量。`1h` 为小时值，`1d` 为当天各小时的总和。
`data[].aggregate.total_supply`	该饰品的大致累计供应量。仅 `aggregate`。

每个归档分桶上都存在 bucket。
平台对象仅在该平台在该分桶中有数据时出现。
没有归档数据的有效请求饰品返回 not_in_archive。

完整结构：ArchiveHistoryItem、ArchiveHistoryBucket、ArchiveHistoryPlatformData。

错误#

404 not_found 表示请求中的有效饰品均没有归档数据。部分结果返回 200 和 errors[]；饰品错误代码包括 unknown_item、invalid_format 和 not_in_archive。见部分成功和请求错误。