Read a Listopia list
A reader-voted Listopia list such as Best Books Ever, with each book’s rank, score and voter count; or, given a tag, the lists with that tag. Give exactly one of list or tag. Up to 500 books (150 lists for a tag) in one request, continuing with a cursor. 1 credit per 100 books, or per 30 lists.
/list Quotes, series & lists https://api.fetchlayer.dev/goodreads/list Headers
Authorization string required Bearer token — your FetchLayer API key.
Parameters
list integer | string optional The list: a Listopia list id (1) or list URL.
tag string optional Instead of list: return the lists with this tag, e.g. fantasy.
limit integer optional How many books to return, 1–500 (lists for a tag: 1–150). Books come 100 to a page and lists 30 to a page; each page is 1 credit. (default: 100)
cursor string optional The nextCursor from a previous response, passed back with the same other parameters, to continue where it stopped.
format string optional json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON. (default: json)
timeoutMs number optional Per-request time limit in milliseconds (max 600000).
Response Fields
list
Read a Listopia list
transport string The data source: always the platform id, "goodreads".
notes string[] Caveats about this response you can act on, such as a series listing fewer works than its total. Empty when there are none.
id number The list id (list requests).
title string The list’s title; description is alongside.
totalBooks number | null Books on the list in all.
totalVotes number | null Votes cast on the list.
bookCount number Books in this response.
books object[] The books in rank order, in the book-summary shape.
books[].rank number | null Its rank on the list.
books[].score number | null Its Listopia score.
books[].votes number | null How many people voted for it.
lists object[] Tag requests: { id, title, url, books, voters } for each list with the tag; listCount counts them.
totalCount number | null How many books or lists Goodreads has for this request in all, when it says.
nextCursor string | null Pass back as cursor, with the same other parameters, to continue. null when there is nothing further.
hasNextPage boolean Whether more books or lists remain.
pagesScraped number Pages of results this response covers, which is what it costs: one credit per page.
Request
curl -X POST "https://api.fetchlayer.dev/goodreads/list" \
-H "Authorization: Bearer ss-your-key" \
-H "Content-Type: application/json" \
-d '{"list":1,"limit":10}'Response
{
"transport": "goodreads",
"notes": [],
"id": 1,
"url": "https://www.goodreads.com/list/show/1",
"title": "Best Books Ever",
"description": "The best books ever, as voted on by the general Goodreads community.\n\nNote to librarians: do not edit this list's description.",
"totalBooks": 80143,
"totalVotes": 298645,
"bookCount": 10,
"books": [
{
"id": 2767052,
"workId": null,
"title": "The Hunger Games (The Hunger Games, #1)",
"url": "https://www.goodreads.com/book/show/2767052-the-hunger-games",
"coverUrl": "https://i.gr-assets.com/images/S/compressed.photo.goodreads.com/books/1586722975i/2767052._SX50_.jpg",
"authors": [
{
"id": 153394,
"name": "Suzanne Collins",
"url": "https://www.goodreads.com/author/show/153394.Suzanne_Collins"
}
],
"rating": {
"average": 4.36,
"count": 10346015,
"reviewCount": null
},
"firstPublishedYear": null,
"editionsCount": null,
"rank": 1,
"score": 4577337,
"votes": 46509
}
],
"nextCursor": "1.10",
"hasNextPage": true,
"pagesScraped": 1
}