> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindcase.co/llms.txt
> Use this file to discover all available pages before exploring further.

# IMDb Videos API

> IMDb titles with original title, type, year, end year and the IMDb URL. Search by keyword or pass title IDs.

`POST /v1/data/imdb/videos/run`

**Pricing:** $0.003 per video ($3.00 per 1,000).

## Ways to call it

* **Search Queries**: set `searchQueries` (optional: `type`, `yearFrom`, `yearTo`, `maxResults`)
* **Title IDs**: set `titleIds` (optional: `type`, `yearFrom`, `yearTo`, `maxResults`)

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**searchQueries** `string[]`

One or more search queries. One request reads them all.

**titleIds** `string[]`

One or more title ids. One request reads them all.

**type** `string`

Type to use.

Allowed values: `movie` (Movies only), `tv` (TV shows only).

**yearFrom** `integer`

Year From as a whole number.

Min `1874`; max `2100`.

**yearTo** `integer`

Year To as a whole number.

Min `1874`; max `2100`.

**maxResults** `integer` (default: 100)

How many videos to return in total. Defaults to 100; use 0 for all.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/imdb/videos/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "searchQueries": [
      "The Shawshank Redemption",
      "Dune",
      "RRR"
    ],
    "titleIds": [],
    "maxResults": 10
  }
}'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.mindcase.co/v1/data/imdb/videos/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "searchQueries": [
        "The Shawshank Redemption",
        "Dune",
        "RRR"
    ],
    "titleIds": [],
    "maxResults": 10
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/imdb/videos/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "searchQueries": [
    "The Shawshank Redemption",
    "Dune",
    "RRR"
  ],
  "titleIds": [],
  "maxResults": 10
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one video, keyed by these fields.

| Field | Name | Type |
| - | - | - |
| `imdbId` | Imdb ID | text |
| `title` | Title | text |
| `originalTitle` | Original Title | text |
| `imdbUrl` | Imdb URL | url |
| `type` | Type | text |
| `year` | Year | number |
| `endYear` | End Year | number |
| `releaseDate` | Release Date | date |
| `rating` | Rating | rating |
| `votes` | Votes | number |
| `runtimeMin` | Runtime Min | number |
| `genres` | Genres | array |
| `plot` | Plot | text |
| `certificate` | Certificate | text |
| `metascore` | Metascore | number |
| `metascoreReviews` | Metascore Reviews | number |
| `topRank` | Top Rank | number |
| `countries` | Countries | array |
| `languages` | Languages | array |
| `isSeries` | Is Series | boolean |
| `isEpisode` | Is Episode | boolean |
| `seasons` | Seasons | number |
| `totalEpisodes` | Total Episodes | number |
| `isOngoing` | Is Ongoing | boolean |
| `budget` | Budget | number |
| `budgetCurrency` | Budget Currency | text |
| `grossWorldwide` | Gross Worldwide | number |
| `grossWorldwideCurrency` | Gross Worldwide Currency | text |
| `openingWeekendGross` | Opening Weekend Gross | number |
| `openingWeekendCurrency` | Opening Weekend Currency | text |
| `openingWeekendEndDate` | Opening Weekend End Date | date |
| `openingWeekendTheaters` | Opening Weekend Theaters | number |
| `trailerUrl` | Trailer URL | url |
| `trailerDurationS` | Trailer Duration S | number |
| `image` | Image | image |
| `totalCast` | Total Cast | number |
| `directors` | Directors | object\_array |
| `creators` | Creators | object\_array |
| `writers` | Writers | object\_array |
| `stars` | Stars | object\_array |
| `cast` | Cast | object\_array |
| `similarTitles` | Similar Titles | object\_array |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "imdb/videos",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "trailerDurationS": 131,
      "releaseDate": "1994-10-14",
      "votes": 3260233,
      "imdbId": "tt0111161",
      "isSeries": false,
      "grossWorldwideCurrency": "USD",
      "directors": [
        {
          "id": "nm0001104",
          "name": "Frank Darabont",
          "link": "https://www.imdb.com/name/nm0001104/"
        }
      ],
      "openingWeekendTheaters": 33,
      "title": "The Shawshank Redemption",
      "image": "https://m.media-amazon.com/images/M/MV5BMDAyY2FhYjctNDc5OS00MDNlLThiMGUtY2UxYWVkNGY2ZjljXkEyXkFqcGc@._V1_.jpg",
      "budgetCurrency": "USD",
      "openingWeekendEndDate": "1994-09-25",
      "stars": [
        {
          "id": "nm0000209",
          "name": "Tim Robbins",
          "link": "https://www.imdb.com/name/nm0000209/"
        },
        {
          "id": "nm0000151",
          "name": "Morgan Freeman",
          "link": "https://www.imdb.com/name/nm0000151/"
        }
      ],
      "writers": [
        {
          "id": "nm0000175",
          "name": "Stephen King",
          "link": "https://www.imdb.com/name/nm0000175/"
        },
        {
          "id": "nm0001104",
          "name": "Frank Darabont",
          "link": "https://www.imdb.com/name/nm0001104/"
        }
      ],
      "type": "movie",
      "runtimeMin": 142,
      "grossWorldwide": 29425588,
      "countries": [
        "United States"
      ],
      "year": 1994,
      "originalTitle": null,
      "totalCast": 74,
      "openingWeekendCurrency": "USD",
      "totalEpisodes": null,
      "genres": [
        "Drama"
      ],
      "cast": [
        {
          "id": "nm0000209",
          "name": "Tim Robbins",
          "link": "https://www.imdb.com/name/nm0000209/",
          "characters": [
            "Andy Dufresne"
          ],
          "image_link": "https://m.media-amazon.com/images/M/MV5BMTI1OTYxNzAxOF5BMl5BanBnXkFtZTYwNTE5ODI4._V1_.jpg",
          "image_width": null,
          "image_height": null
        },
        {
          "id": "nm0000151",
          "name": "Morgan Freeman",
          "link": "https://www.imdb.com/name/nm0000151/",
          "characters": [
            "Ellis Boyd 'Red' Redding"
          ],
          "image_link": "https://m.media-amazon.com/images/M/MV5BNzExODU5YjktYmJlZC00YzllLWE0MWEtZTBlYmZkMGM0MTExXkEyXkFqcGc@._V1_.jpg",
          "image_width": null,
          "image_height": null
        }
      ]
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.