Magnus Hedemarkandfactory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
cc962bb298
SKILL.md essential commands show --page usage, add a seq/jq page-loop
recipe driven by the pagination.page_count field of the JSON output
(with 429 Retry-After handling), and document that --json emits
movies/shows plus the normalized pagination object whose keys mirror
X-Pagination-* headers, degrading to {} when headers are absent; human
output notes the Page N of M footer rule. References state
per-invocation paging and the same degradation fallback. Evals replace
the header-only pagination case with an executable loop case and a
second-page trending case asserting --page, pagination keys, and array
preservation. README Quick Start and test-table rows updated to match.
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
3.0 KiB
Trakt discovery endpoints
All endpoints below are GET requests at https://api.trakt.tv and use the request contract in auth-and-request-contract.md.
| Endpoint | Meaning | Response shape |
|---|---|---|
/movies/trending |
Most watched movies in the last 24 hours, ordered by watchers | wrapper objects with watchers and nested movie |
/movies/popular |
Popularity based on rating percentage and number of ratings | movie objects |
/movies/anticipated |
Upcoming interest based on list appearances | movie objects |
/shows/trending |
Most watched shows in the last 24 hours, ordered by watchers | wrapper objects with watchers and nested show |
/shows/popular |
Popularity based on rating percentage and number of ratings | show objects |
/shows/anticipated |
Upcoming interest based on list appearances | show objects |
Trending is a short, current watch signal. Popular is a broad popularity ranking, while anticipated is an upcoming-interest signal. Do not treat a trending rank as a release calendar or a popularity score as a personalized recommendation.
Paging and filters
These feeds accept page and limit; compatibility defaults are page 1 and limit 10. Set both explicitly for reproducible automation. Responses provide X-Pagination-Page, X-Pagination-Limit, X-Pagination-Page-Count, and X-Pagination-Item-Count. Stop at the reported page count instead of assuming a short page means completion.
The bundled CLI forwards --page and --limit to the query string and normalizes those four headers into a JSON pagination object with the keys page, limit, page_count, and item_count. Keys are integers when the headers were present; the object is {} when the headers are missing, so downstream jq can fall back with .pagination.page_count // 1.
Endpoint pages also document filters such as extended, watchnow, genres, years, ratings, date ranges, countries, and ignore_watched, ignore_collected, and ignore_watchlisted where supported. Encode comma-separated values as query parameters. watchnow=any means any service, while any_all and the free_all/subscriptions_all forms have stricter all-country semantics.
Result normalization
For trending responses, unwrap movie or show before reading title, year, and IDs, but preserve watchers if ranking matters. Popular and anticipated responses are already direct media objects. Trakt IDs are not TMDb metadata: use the returned ids object to hand an identifier to another tool, and use TMDb when the task is catalog metadata, credits, images, or provider details.
Sources
- https://docs.trakt.tv/reference/getmoviestrending
- https://docs.trakt.tv/reference/getmoviespopular
- https://docs.trakt.tv/reference/getmoviesanticipated
- https://docs.trakt.tv/reference/getshowstrending
- https://docs.trakt.tv/reference/getshowspopular
- https://docs.trakt.tv/reference/getshowsanticipated
- https://trakt.docs.apiary.io/reference/movies/trending/get-trending-movies