Contents

Endpoints

Films

Operations about films

Relative to https://api.showtimes-api.com/v4.

Get films

GET/films

Get a paginated list of films currently showing in cinemas in the countries the request reads.

Parameters

page integer in query

Page offset to fetch.

Default: 1.

items integer in query

Number of items to return per page.

Default: 20.

cursor string in query

Use cursor pagination. Send an empty cursor for the first page. Then send meta.next_cursor from each response as cursor. When next_cursor is null, you have all the results.

A cursor walk gives films in id order, not in page order. You get a film that is added during the walk only if its id is after the cursor.

With a cursor, meta has next_cursor and not page, and the API ignores the page parameter. You cannot use cursor with search_query.

country string in query

Get results only for these countries: comma-separated ISO 3166-1 alpha-2 codes, for example IE or GB,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 /countries lists both.

cinema_id integer in query

Filter by a specific cinema.

include_outdated boolean in query

Include films that are no longer showing in cinemas.

Default: false.

search_query string in 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_id integer in query

Filter by a specific TMDB ID.

imdb_id string in query

Filter by a specific IMDB ID.

Response

200 Returns films with pagination metadata. (FilmsResponse)

Errors: 400, 401, 403, 429, 500
  • 400 Bad 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.
  • 401 Unauthorized – the request requires valid authentication.
  • 403 Forbidden – authentication succeeded but access is denied (e.g., expired subscription, or a country your key does not include).
  • 429 Too 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.
  • 500 Internal Server Error – something went wrong on our end.
Example response
{
  "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"
    }
  ]
}

Get film

GET/films/{id}

Returns a film.

Parameters

id integer in path required

Film ID.

country string in query

Get results only for these countries: comma-separated ISO 3166-1 alpha-2 codes, for example IE or GB,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 /countries lists both.

Response

200 Returns a film. (Film)

Errors: 400, 401, 403, 404, 429, 500
  • 400 Bad 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.
  • 401 Unauthorized – the request requires valid authentication.
  • 403 Forbidden – authentication succeeded but access is denied (e.g., expired subscription, or a country your key does not include).
  • 404 Not found
  • 429 Too 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.
  • 500 Internal Server Error – something went wrong on our end.
Example response
{
  "id": 579691593,
  "title": "Royal Ballet & Opera 2026/27: Carmen",
  "original_title": "RBO Cinema Season 2026-27: Carmen",
  "events_count": 198,
  "imdb_id": "tt43657998",
  "tmdb_id": 1702759,
  "release_year": 2026,
  "runtime": 215,
  "original_language": "fra"
}