history
Retrieve recently played items from the local playback log. Filter by time, media type, artist, or text; paginate results or get a count.
Instructions
List recently played items from the local playback log. Filter with an ISO-8601 window (since/until), media/kind/artist, a free-text match or an exact id; page with limit/offset/order, or ask for a count only. An omitted instance returns all boxes. Reads only the local log — no Kodi call, so it works even when no box is reachable. Returns { "total", "returned", "offset", "truncated", "entries": [ { "at", "instance", "kind", "media", "title", "artist", … } ] }.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Restrict to one Kodi instance by key. Omitted returns entries from ALL instances — note this differs from other tools, where an omitted instance means the default box. | |
| since | No | Only entries at or after this ISO-8601 time (e.g. "2026-06-01T00:00:00Z"). Omitted = from the beginning of the log. Compute relative windows ("last 7 days") yourself. | |
| until | No | Only entries at or before this ISO-8601 time. Omitted = up to now. | |
| limit | No | Max entries to return (default 50, max 1000). When more match, the reply sets "truncated": true — page the rest with offset. | |
| offset | No | Number of matching entries to skip before this page — paginate together with limit, keeping the same order. | |
| order | No | Result order: "newest" first (default) or "oldest" first to replay a session in the order it happened. | |
| count | No | When true, return only the total match count (zero entries) — a cheap "how many times / how much did X play". | |
| media | No | Keep only entries of this media kind (song/episode/movie/musicvideo/picture/channel) — e.g. "movies only". | |
| kind | No | Keep only entries of this broad kind: audio or video — e.g. "what music did I play". | |
| artist | No | Keep only entries whose performer contains this (substring, case-insensitive) — the music-by-artist filter ("everything Pink Floyd I played"). Only as good as the captured artist tag. | |
| match | No | Free-text substring (case-insensitive) over an entry's human fields — title, album, show, label and artist — to narrow the log without knowing ids. | |
| id | No | Exact library id to match ("every time THIS item played"). Ids are per media type, so pair with media; feed back a searchmedia or getplaylist row's id. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | The instance filter, echoed when one was given. | |
| since | No | The window's lower bound, echoed when one was given. | |
| until | No | The window's upper bound, echoed when one was given. | |
| total | Yes | Full match count, before any paging. | |
| returned | Yes | Rows in this page. | |
| offset | Yes | Rows skipped before this page. | |
| truncated | Yes | Whether matches remain beyond this page. | |
| entries | Yes | The matching history records. |