Goodreads hub

Goodreads Lists API

The Listopia lists that carry a tag.

GET /v1/goodreads/lists

1 credit Failed requests are free A not-found answer is still charged

About this endpoint

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.

Price

From $1.35 per 1,000 requests

1 credit per request. Failed requests are free.

Scale pack
$1.64 / 1,000
Growth pack
$2.36 / 1,000

The lowest rate is on annual plans; packs are pay as you go.

Example request

Send your API key in the x-api-key header. New accounts get 100 free credits, no card needed.

Request
cURL

Example response

A 200 response. Live responses have the same shape with current data.

Request
JSON

Goodreads Lists API 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.