> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/goodreads/lists-listid>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/goodreads/lists-listid.mdx>

---

# Goodreads Listopia List API

A Listopia list with its ranked books, scores and votes.

`GET /v1/goodreads/lists/{listId}` takes the number from the list URL, for example `1` for Best Books Ever. On `found`, `data.list` carries `id`, `title`, `url`, `description`, `booksCount`, `voters`, `likes`, `tags` and `books`, each with `rank`, `score`, `votes`, `id`, `title`, `url`, `cover`, `authors`, `averageRating` and `ratingsCount`. 100 books a page; follow `page.nextPage` while `page.hasMore` is true.

## Request

- **Endpoint:** `GET /v1/goodreads/lists/{listId}`
- **Credits:** 1 credit
Failed requests are free
A not-found answer is still charged
- **Input:** by list id
- **Full reference:** [docs](https://www.socialfetch.dev/docs/api/v1/goodreads/lists/listid/get)
- **Platform page:** [/platforms/goodreads](https://www.socialfetch.dev/platforms/goodreads)

## FAQ

### How are books ranked?

By the list score the site computes from the number of voters and how highly they ranked each book. rank, score and votes are returned as the site shows them.

### How deep can I page?

As deep as the list goes, 100 books a page. Long lists such as Best Books Ever run to hundreds of pages.

### How many credits does a call cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged: that field is the billing source of truth.

### What does lookupStatus mean here?

found means data.list is the list. not_found means no list has this id.
