Developer
DocumentationContact Us
  • Documentation
  • Key Concepts
  • Overview
  • Getting Access to the API
  • API Key Concepts
  • Calling the API
  • Sample Queries
  • Title/Name
  • Box Office
  • Search
  • Overview
  • Bulk Data Key Concepts
  • Data Dictionary
  • Names
  • Titles
  • Box Office
  • Meters
  • Parents Guide
  • Querying In Athena
  • Creating Tables DDL
  • Release Notes

Sample queries: Title/Name

Queries to help you get started with essential IMDb data: title ratings, title metadata, top cast and more.

Example 1

Average Rating for Suicide Squad

Supported on the Ratings, IMDb Title and Name Essentials, and Box Office API.

To query the current IMDb star rating for Suicide Squad (2021) along with the total number of user ratings for that title, the query would include the following:

    • QUERY
    • RESULT
  • 1 2 3 4 5 6 7 8 query { title(id: "tt6334354") { ratingsSummary { aggregateRating voteCount } } }

    Result size: 71 bytes

    The response returns (at the time of the data pull) Suicide Squad with an aggregateRating of 7.2 based on 384,799 unique user ratings.

    Example 2

    Get Plot Texts and Genres

    Supported on the IMDb Title and Name Essentials, and Box Office API products.

    To query a request for the first two plot texts, genre, and ratings certificate details for It (2017):

    • QUERY
    • RESULT
  • 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 query { title(id: "tt1396484") { titleGenres { genres { genre { text } } } plots(first: 2) { edges { node { plotText { plainText } } } } certificate { rating ratingReason } } }

    Result size: 693 bytes

    The response returns the plotText in the "plainText" node fields followed by the "R" rating and the ratingReason provided by the MPA."

    Example 3

    Runtime, Release Date, Coloration

    Supported on the IMDb Title and Name Essentials, and Box Office API products.

    To query runtime, release date, and color info for Wall-E:

    • QUERY
    • RESULT
  • 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 query { title(id: "tt0910970") { runtime { seconds } releaseDate { day month year } technicalSpecifications { colorations { items { text } } } } }

    Result size: 156 bytes

    The response returns runtime in seconds (5,880), release date broken down by day/month/year (6/27/2008), and that the film was in "Color.

    Example 4

    Credits

    Supported on the IMDb Title and Name Essentials, and Box Office API products.

    To query WALL-E credits:

    • QUERY
    • RESULT
  • 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 query { # Get WALL·E title(id: "tt0910970") { # Get the first two credits for WALL·E credits(first: 2) { edges { node { # Get the name associated with that credit name { nameText { text } } # Get the category for that credit (e.g Actor, Director) category { text } } } } } }

    Result size: 199 bytes

    The response returns the first two credits listed along with the name text (Ben Burtt and Elissa Knight) and the job category (Actor and Actress).

    Example 5

    Querying multiple categories of credits

    Supported on the IMDb Title and Name Essentials, and Box Office API products.

    To query directors, writers and cast for Joker:

    • QUERY
    • RESULT
  • 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 query { #Get Joker title(id: "tt7286456") { # Get first five directors DIRECTORS: credits(first: 5, filter: { categories: ["director"] }) { edges { node { name { nameText { text } } } } } # Get first five writers WRITERS: credits(first: 5, filter: { categories: ["writer"] }) { edges { node { name { nameText { text } } } } } # Get first five cast CAST: credits(first: 5, filter: { categories: ["actor", "actress"] }) { edges { node { name { nameText { text } } } } } } }

    Result size: 686 bytes

    You can't directly query for the same field with different arguments. That's why you need aliases - they let you rename the result of a field to anything you want.

    Example 6

    Known For Titles from Credits

    Supported on the IMDb Title and Name Essentials, and Box Office API products.

    This sample query highlights the power of GraphQL. The query returns cast credits on Inception and dives a layer deeper to query the "known for" titles for each actor alongside their character name and the movie's IMDb Star Rating:

    • QUERY
    • RESULT
  • 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 query { # Get the movie Inception title(id: "tt1375666") { # Get the first two credits on Inception credits(first: 2) { edges { node { # Get the name associated with a given credit name { nameText { text } # Get the first two titles that name is known for knownFor(first: 2) { edges { node { title { #Get the title text for the title that the name is known for titleText { text } # Get the rating for that title that the name is known for ratingsSummary { aggregateRating } } summary { # Get the name of the charachter that they played in the title they are known for principalCharacters { name } } } } } } } } } }

    Result size: 793 bytes

    The response returns that Leonardo DiCaprio is known for both Inception (IMDb Rating of 8.8) - where he played Cobb - and Titanic (7.9) - where he played Jack and that Joseph Gordon-Levitt is known for both Inception (8.8) - where he played Arthur - and Looper (7.4) - where he played Joe.

    Example 7

    Title Keywords

    Supported on the IMDb Title and Name Essentials, and Box Office API products.

    IMDb provides keywords associated with each title in the dataset alongside user votes of how "relevant" that keyword is for the movie. To include keywords from Inception and The Dark Knight in this query:

    • QUERY
    • RESULT
  • 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 { # Get Inception and The Dark Knight titles(ids: ["tt1375666", "tt0468569"]) { # Get the first keyword for each title keywords(first: 1) { edges { node { # Get the keyword text keyword { text { text } } # Get the number of interesting votes for this keyword interestScore { usersInterested usersVoted } } } } } }

    Result size: 270 bytes

    The response returns IMDb users sentiment reflecting "dream" as the most relevant keyword for Inception while "dc comics" is most relevant for The Dark Knight.

    Example 8

    Name Awards

    Supported on the IMDb Title and Name Essentials, and Box Office API products.

    IMDb provides information on the cast and crew involved in movies and TV series. To query the first three awards won by three different actors - Jennifer Lawrence, Morgan Freeman, and Patrick Swayzee:

    • QUERY
    • RESULT
  • 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 query { # Get Jennifer Lawrence, Morgan Freeman and Patrick Swayzee names(ids: ["nm2225369", "nm0000664", "nm0000151"]) { nameText { text } # Get the first 3 awards that a given name won awardNominations(first: 3, filter: { wins: WINS_ONLY }) { edges { node { award { # Get the award text for a given award text # Get the name of the event the award was given event { text } # Get the year of the award year } } } } } }

    Result size: 1,203 bytes

    The response returns three awards per person queried. You can also find awards by year, event, and whether a cast or crew member was nominated or won an award.

    Example 9

    Episodes

    Supported on the IMDb Title and Name Essentials, and Box Office API products.

    IMDb provides data for global TV series as well as movies. To query episodes from Futurama:

    • QUERY
    • RESULT
  • 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 query { # Get Futurama title(id: "tt0149460") { # Get the title type of Futurama (TV Series) titleType { text canHaveEpisodes } # Get the first three episodes of Futurama episodes { episodes(first: 3) { edges { node { # Get the names of the episodes titleText { text } } } pageInfo{ endCursor hasNextPage } } } } }

    Result size: 391 bytes

    The response returns Futuramas first three episodes: "Space Pilot 3000," "The Series Has Landed," and "I, Roommate."

    Example 10

    Episodes - Pagination

    Supported on the IMDb Title and Name Essentials, and Box Office API products.

    This example demonstrates how to use cursor-based pagination to retrieve next 3 episodes for Futurama.

    • QUERY
    • RESULT
  • 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 query { # Get Futurama title(id: "tt0149460") { # Get the title type of Futurama (TV Series) titleType { text canHaveEpisodes } # Get the next three episodes of Futurama episodes { episodes(first: 3, after:"dHQwNzU2ODgy") { edges { node { # Get the names of the episodes titleText { text } } } pageInfo{ endCursor hasNextPage } } } } }

    Result size: 407 bytes

    The response returns a list of 3 episodes starting from the 4th episode. Use the 'endCursor' value as the 'after' parameter in your next query to retrieve more episodes. Note that cursors are temporary and may change, so do not store them for future use.

    Sample Queries - Box Office

    Get started with our box office data learning about lifetime grosses, regional results, and weekend returns.

    Get started

    Contact us to see how IMDb data can solve your customers needs.

    Contact Us
    • Conditions of Use
    • Privacy Policy

    © 1990-2025 by IMDb.com, Inc.