---
title: "查询播放上下文的播放历史"
method: GET
path: "/play-history"
tags: ["播放历史"]
---

# 查询播放上下文的播放历史

`GET /play-history`

返回指定播放上下文内最近播放过的歌曲，按最后播放时间倒序，含完整歌曲详情。
「播放上下文」由 context_type + context_key 二元组标识：歌单为 (playlist, 歌单 ID)，分面维度为 (artist, 歌手名) / (album, 专辑名) 等。
同一上下文内按歌曲去重（重复播放只刷新时间并累加 play_count），最多保留最近 50 条，因此本端点不分页。
记录由 POST /songs/{id}/played 在 type=play 时写入。歌曲从库中删除时其历史自动级联清理；歌曲仅被移出歌单时历史仍保留，客户端起播时自行判定失效。

## Query parameters

- `context_type` 'playlist' | 'artist' | 'album' | 'genre' | 'year' | 'decade' | 'language' | 'style', required
- `context_key` string, required
- `limit` integer

## Response `200`

成功返回播放历史列表

- ModelsPlayHistoryListResponse
  - `items` ModelsPlayHistoryEntry[] — 播放记录，按最后播放时间倒序
    - `play_count` integer — 在该上下文内的累计播放次数
    - `played_at` string — 最后一次播放时间
    - `song` ModelsSong
      - `added_at` string — 添加时间
      - `album` string — 专辑名称
      - `artist` string — 艺术家/歌手
      - `bit_rate` integer — 比特率（kbps）
      - `cover_url` string — 封面图片URL
      - `cue_source_path` string — CUE 来源路径（非空表示 CUE 拆分歌曲）
      - `cue_track_index` integer — CUE track 序号 (1-99)
      - `dedup_key` string — 去重 key(由插件定义,典型形态 "<platform>:<platform_id>");与 PluginEntryPath 组成 UNIQUE
      - `duration` number — 播放时长（秒）
      - `file_modified_at` string — 文件修改时间(mtime，本地歌曲扫描时记录；未知为 nil)
      - `file_path` string — 本地文件路径
      - `file_size` integer — 文件大小（字节）
      - `fingerprint` string — 音频指纹(Chromaprint)
      - `fingerprint_duration` number — 指纹对应音频时长
      - `format` string — 音频格式
      - `genre` string — 流派
      - `id` integer — 歌曲ID
      - `is_live` boolean — 是否为直播流
      - `is_video` boolean — 是否含真实视频轨(扫描时 ffprobe 探测,排除封面);客户端据此渲染画面/选择投屏 mime
      - `isrc` string — ISRC(国际标准录音编码)
      - `language` string — 语种
      - `lyric_remote_url` string — lyric_source=url 时的原始 URL(运行时由 LyricFetcher 拉取)
      - `lyric_url` string — 歌词端点 URL(客户端唯一可见字段,指向 /api/v1/songs/{id}/lyric)
      - `plugin_entry_path` string — 音源插件 entryPath(网络歌曲)
      - `sample_rate` integer — 采样率（Hz）
      - `source_cover_url` string — 原始封面 URL(仅 JSON 输出,CoverURL 非空时保留原始值供编辑使用)
      - `source_data` string — 音源元数据 JSON(给插件 music/url 接口用,opaque)
      - `source_url` string — 原始音源 URL(仅 JSON 输出,radio/remote 类型返回原始流地址供编辑使用)
      - `style` string — 风格
      - `title` string — 标题
      - `track` string — 音轨号，可为 "3" 或 "3/12"（轨号/总数）
      - `type` 'local' | 'remote' | 'radio' — 歌曲类型：local/remote/radio
      - `updated_at` string — 最后更新时间
      - `url` string — 网络地址
      - `year` integer — 发行年份
  - `total` integer — 本次返回的条数（上限 50，故与 items 长度一致）

## Other responses

- `400` — context_type 不支持或缺少 context_key
- `500` — 服务器错误

---

[API](https://skmtc.net/songloft-org/apis/songloft-api.md) · [All operations](https://skmtc.net/songloft-org/apis/songloft-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/songloft-org/songloft-api/revisions/3597db751d49/schema)