Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.discovr.media/llms.txt

Use this file to discover all available pages before exploring further.

Retrieves all history entries for a specific media item from the history list. Items are returned in descending order by updated date (newest first). Supports cursor-based pagination using the nextPageToken query parameter. Pagination:
  • Use nextPageToken from the previous response to fetch the next page
  • If hasMore is true, there are more items available on subsequent pages.
Duplicates: Unlike other lists, the history list allows duplicate entries. Each watch event creates a new history entry. This endpoint returns all matching history entries for the specified media. TV Shows: For TV shows, season query parameter is required. episode is optional - if not provided, returns all history entries for the specified season (including season default entries). When a TV history item has no episode field, it represents a “Default for Episode” entry. Frontend clients should treat these entries as applying to all episodes in the season where episode.air_date < historyItem.updatedAt. This allows updating multiple episodes with a single history entry. The matching logic is a client-side concern and not exposed by the API. Entry Precedence: When processing history entries, explicit episode entries (with episode specified) take precedence over season default entries. If an episode has both a season default entry and an explicit entry, the explicit entry’s completion status and progress should be used. Season defaults only apply to episodes that do not have explicit entries. Movies: For movies, no additional parameters are needed. Media Assets: All items include media assets (id, title, poster_path, backdrop_path) automatically.

​
Parameters

NameTypeRequiredDescription
mediaIdstringYesThe DiscovrID (TV_<tmdbId> or MV_<tmdbId>) of the media item
seasonintegerNoSeason number (required for TV shows only, must be provided when mediaId starts with TV_)
episodeintegerNoEpisode number (optional for TV shows, only valid when mediaId starts with TV_). If not provided, returns all episodes in the season.
nextPageTokenstringNoOpaque token from previous page for pagination
limitintegerNoMaximum number of items to return (1-50, default: 10)

​
Returns

HistoryListResponse — List of history items retrieved successfully 
{
  "items": [
{
  "id": "string",
  "mediaType": "movie" /* enum: "movie", "tv" */,
  "title": "string",
  "poster_path": "string",
  "backdrop_path": "string",
  "updatedAt": "string" /* date-time */,
  "progress": 0.0,
  "completed": false,
  "watched_count": 0,
  "season": 0,
  "episode": 0,
  "imported": "string",
  "createdAt": "string" /* date-time */
}
],
  "hasMore": false,
  "nextPageToken": "string"
}

​
Example

import { DiscovrClient } from "discovr";
import type { HistoryListResponse } from "discovr";

const discovr = new DiscovrClient("your-client-id", {
  basePath: "https://api.discovr.media",
});

// After sign-in and profile selection …
const response: HistoryListResponse = await discovr.getHistoryItemsByMediaId("TV_1396", { season: 1, episode: 5, nextPageToken: "example", limit: 10 });
console.log(response);