Get films
GET/films
Get a paginated list of films currently showing in cinemas in the countries the request reads.
Parameters
-
pageintegerin query -
Page offset to fetch.
Default:
1. -
itemsintegerin query -
Number of items to return per page.
Default:
20. -
cursorstringin query -
Use cursor pagination. Send an empty
cursorfor the first page. Then sendmeta.next_cursorfrom each response ascursor. Whennext_cursorisnull, you have all the results.A cursor walk gives films in
idorder, not in page order. You get a film that is added during the walk only if itsidis after the cursor.With a cursor,
metahasnext_cursorand notpage, and the API ignores thepageparameter. You cannot usecursorwithsearch_query. -
countrystringin query -
Get results only for these countries: comma-separated ISO 3166-1 alpha-2 codes, for example
IEorGB,IE. Without it, you get all the countries that your key includes. A country that your key does not include gives 403. A country that the API does not serve gives 400.GET /countrieslists both. -
cinema_idintegerin query -
Filter by a specific cinema.
-
include_outdatedbooleanin query -
Include films that are no longer showing in cinemas.
Default:
false. -
search_querystringin query -
Search for films by title, director name, TMDB ID, or IMDB ID. At most 256 characters and 64 words; a longer query is refused with a 400, and so is one that matches too many terms to search.
-
tmdb_idintegerin query -
Filter by a specific TMDB ID.
-
imdb_idstringin query -
Filter by a specific IMDB ID.
Response
200 Returns films with pagination metadata. (FilmsResponse)
Errors: 400, 401, 403, 429, 500
400Bad request – e.g. an invalid cursor, a country the API does not serve, a filter that is not valid, or a query parameter that the endpoint does not have. The message names the parameter.401Unauthorized – the request requires valid authentication.403Forbidden – authentication succeeded but access is denied (e.g., expired subscription, or a country your key does not include).429Too Many Requests – the limit is 5 requests per second for a Pro account. An account with Ultra in one or more countries has 20. An account with Lite in all its countries has 1, and 1000 requests each day. The day starts at 00:00 UTC. All the keys of an account share the limit. The limit is not for each country. The error message gives the limit that applied.500Internal Server Error – something went wrong on our end.
curl -H "Authorization: Bearer YOUR_API_TOKEN" "https://api.showtimes-api.com/v4/films"
const response = await fetch("https://api.showtimes-api.com/v4/films", {
headers: { Authorization: "Bearer YOUR_API_TOKEN" },
})
const body = await response.json()
import requests
response = requests.get(
"https://api.showtimes-api.com/v4/films",
headers={"Authorization": "Bearer YOUR_API_TOKEN"},
)
body = response.json()
require "json"
require "net/http"
response = Net::HTTP.get_response(
URI("https://api.showtimes-api.com/v4/films"),
{"Authorization" => "Bearer YOUR_API_TOKEN"}
)
body = JSON.parse(response.body)
{
"meta": {
"page": 1,
"per_page": 20,
"total_count": 1116
},
"data": [
{
"id": 296557755,
"title": "Scream 7",
"original_title": "Scream 7",
"events_count": 17308,
"imdb_id": "tt27047903",
"tmdb_id": 1159559,
"release_year": 2026,
"runtime": 114,
"original_language": "eng"
}
]
}