> **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>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/goodreads/lists.mdx>

---

# Goodreads Lists API

The Listopia lists that carry a tag.

`GET /v1/goodreads/lists?tag=` returns the Listopia lists that carry a tag, for example `fantasy`, `romance` or `best`, 30 a page. Each list has `id`, `title`, `url`, `booksCount`, `voters` and the `covers` of its top books. Pass a list's `id` to the list route for its ranked books. An unused tag returns an empty list.

## Request

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

## FAQ

### How do I get the books on a list?

Pass the list id to GET /v1/goodreads/lists/{listId}; it returns the ranked books, 100 a page.

### What tags can I use?

Any Listopia tag, in lowercase with hyphens for spaces, for example science-fiction.

### 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.

### Does an unknown tag fail?

No. It returns an empty lists array with page.hasMore false.
