# TVmaze API

> TVmaze returns TV schedules and show details as a workflow and API.

TVmaze’s Get tv schedule method returns broadcasts and optional streaming releases for a date and country. TVmaze’s Get show method returns show details and optionally a full episode list, using a show name or TVmaze link.

- Page: https://fous.com/tools/tvmaze
- Handle: `@tvmaze`
- Category: [Entertainment](https://fous.com/tools/category/entertainment)
- Source website: https://tvmaze.com
- Last verified: Sep 29, 2026

## Methods

### Get show

Operation `get_show`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get a TV show’s status, schedule, episode information, rating and full episode list from its name or TVmaze show link. The full list includes specials when requested. Time zones and airing times may be unavailable for streaming shows.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `show` | string | yes | `"The Last of Us"` | Show name or TVmaze show link, for example Severance or https://www.tvmaze.com/shows/44933/severance. |
| `include_episodes` | boolean | no | `false` | Include the full episode list, including specials; for example true. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "show"
  ],
  "properties": {
    "show": {
      "type": "string",
      "description": "Show name or TVmaze show link, for example Severance or https://www.tvmaze.com/shows/44933/severance.",
      "examples": [
        "The Last of Us",
        "Severance",
        "https://www.tvmaze.com/shows/522/top-gear"
      ]
    },
    "include_episodes": {
      "type": "boolean",
      "default": true,
      "description": "Include the full episode list, including specials; for example true.",
      "examples": [
        false
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "show": "The Last of Us"
    },
    {
      "show": "Severance"
    },
    {
      "show": "https://www.tvmaze.com/shows/522/top-gear",
      "include_episodes": false
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `name` | string | `"The Last of Us"` |  |
| `genres` | array |  |  |
| `status` | string | `"running"` |  |
| `country` | string or null | `"United States"` |  |
| `summary` | string or null | `"After a global pandemic destroys civilization, a hardened survivor takes charge of a 14-year-old girl who may be humani` |  |
| `end_date` | string or null | `"2022-12-18"` |  |
| `episodes` | array |  |  |
| `episodes[].title` | string or null | `"When You're Lost in the Darkness"` |  |
| `episodes[].number` | integer or null | `1` |  |
| `episodes[].season` | integer or null | `1` |  |
| `episodes[].runtime` | string or null | `"85 minutes"` |  |
| `episodes[].air_date` | string or null | `"2023-01-15"` |  |
| `episodes[].tvmaze_link` | string or null | `"https://www.tvmaze.com/episodes/2423934/the-last-of-us-1x01-when-youre-lost-in-the-darkness"` |  |
| `schedule` | object |  |  |
| `schedule.days` | array |  |  |
| `schedule.time` | string or null | `"21:00"` |  |
| `schedule.time_zone` | string or null | `"America/New_York"` |  |
| `tvmaze_id` | integer | `46562` |  |
| `image_link` | string or null | `"https://static.tvmaze.com/uploads/images/original_untouched/563/1409008.jpg"` |  |
| `tvmaze_link` | string | `"https://www.tvmaze.com/shows/46562/the-last-of-us"` |  |
| `next_episode` | any |  |  |
| `official_site` | string or null | `"https://www.hbo.com/the-last-of-us"` |  |
| `premiere_date` | string or null | `"2023-01-15"` |  |
| `average_rating` | number or null | `7.9` | Average rating out of 10. |
| `previous_episode` | any |  |  |
| `network_or_streaming_service` | string or null | `"HBO"` |  |

**Example input**

```json
{
  "show": "The Last of Us"
}
```

**Example output**

```json
{
  "name": "The Last of Us",
  "genres": [
    "Drama",
    "Action",
    "Horror"
  ],
  "status": "running",
  "country": "United States",
  "summary": "After a global pandemic destroys civilization, a hardened survivor takes charge of a 14-year-old girl who may be humanity's last hope.",
  "end_date": null,
  "episodes": [
    {
      "title": "When You're Lost in the Darkness",
      "number": 1,
      "season": 1,
      "runtime": "85 minutes",
      "air_date": "2023-01-15",
      "tvmaze_link": "https://www.tvmaze.com/episodes/2423934/the-last-of-us-1x01-when-youre-lost-in-the-darkness"
    },
    {
      "title": "Infected",
      "number": 2,
      "season": 1,
      "runtime": "56 minutes",
      "air_date": "2023-01-22",
      "tvmaze_link": "https://www.tvmaze.com/episodes/2446254/the-last-of-us-1x02-infected"
    },
    {
      "title": "Long, Long Time",
      "number": 3,
      "season": 1,
      "runtime": "81 minutes",
      "air_date": "2023-01-29",
      "tvmaze_link": "https://www.tvmaze.com/episodes/2446255/the-last-of-us-1x03-long-long-time"
    }
  ],
  "schedule": {
    "days": [
      "Sunday"
    ],
    "time": "21:00",
    "time_zone": "America/New_York"
  },
  "tvmaze_id": 46562,
  "image_link": "https://static.tvmaze.com/uploads/images/original_untouched/563/1409008.jpg",
  "tvmaze_link": "https://www.tvmaze.com/shows/46562/the-last-of-us",
  "next_episode": null,
  "official_site": "https://www.hbo.com/the-last-of-us",
  "premiere_date": "2023-01-15",
  "average_rating": 7.9,
  "previous_episode": {
    "title": "Convergence",
    "number": 7,
    "season": 2,
    "tvmaze_link": "https://www.tvmaze.com/episodes/3153912/the-last-of-us-2x07-convergence",
    "air_date_time": "2025-05-25T21:00:00-04:00"
  },
  "network_or_streaming_service": "HBO"
}
```

### Get tv schedule

Operation `get_tv_schedule`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get TV broadcasts and, optionally, new streaming episodes scheduled for a date in a country. Worldwide streaming releases are included when streaming is on; airtimes for releases without a local timezone are shown in UTC.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `date` | string | no | `"2026-09-29"` | Schedule date, for example 2026-09-29. Defaults to today. |
| `country` | string | no | `"United States"` | Country name or two-letter code, such as United States or US. |
| `max_results` | integer | no | `25` | Maximum number of episodes, for example 200. |
| `include_streaming` | boolean | no | `false` | Include local and worldwide streaming releases, for example true. |

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "examples": [
        "2026-09-29"
      ],
      "description": "Schedule date, for example 2026-09-29. Defaults to today."
    },
    "country": {
      "type": "string",
      "default": "United States",
      "examples": [
        "United States"
      ],
      "description": "Country name or two-letter code, such as United States or US."
    },
    "max_results": {
      "type": "integer",
      "default": 200,
      "maximum": 500,
      "minimum": 1,
      "description": "Maximum number of episodes, for example 200.",
      "x-fous-developer": true,
      "examples": [
        25,
        200,
        500
      ]
    },
    "include_streaming": {
      "type": "boolean",
      "default": true,
      "description": "Include local and worldwide streaming releases, for example true.",
      "examples": [
        false,
        true
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "date": "2026-09-29",
      "country": "United Kingdom",
      "max_results": 25,
      "include_streaming": false
    },
    {
      "date": "2026-09-29",
      "country": "United States",
      "max_results": 200,
      "include_streaming": true
    },
    {
      "date": "2026-09-29",
      "country": "US",
      "max_results": 500,
      "include_streaming": true
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `episodes` | array |  | Episodes in air-time order. |
| `episodes[].genres` | array |  | Show genres. |
| `episodes[].runtime` | string or null | `"60 min"` | Episode runtime as text, such as 30 min. |
| `episodes[].show_id` | integer or null | `10594` | TVmaze show ID. |
| `episodes[].show_name` | string or null | `"Squawk Box Europe"` | Show name. |
| `episodes[].episode_id` | integer or null | `3724393` | TVmaze episode ID. |
| `episodes[].air_datetime` | string or null | `"2026-09-29T04:00:00+01:00"` | Air date and time in ISO 8601 with an offset, in the service timezone when available. |
| `episodes[].episode_link` | string or null | `"https://www.tvmaze.com/episodes/3724393/squawk-box-europe-2026-09-28-episode-193"` | TVmaze episode page. |
| `episodes[].episode_title` | string or null | `"Episode 193"` | Episode title. |
| `episodes[].season_number` | integer or null | `2026` | Season number. |
| `episodes[].episode_number` | integer or null | `193` | Episode number. |
| `episodes[].runtime_minutes` | integer or null | `60` | Episode runtime in minutes. |
| `episodes[].network_or_streaming_service` | string or null | `"CNBC Europe"` | Broadcast network or streaming service. |

**Example input**

```json
{
  "date": "2026-09-29",
  "country": "United Kingdom",
  "max_results": 25,
  "include_streaming": false
}
```

**Example output**

```json
{
  "episodes": [
    {
      "genres": [],
      "runtime": "60 min",
      "show_id": 10594,
      "show_name": "Squawk Box Europe",
      "episode_id": 3724393,
      "air_datetime": "2026-09-29T04:00:00+01:00",
      "episode_link": "https://www.tvmaze.com/episodes/3724393/squawk-box-europe-2026-09-28-episode-193",
      "episode_title": "Episode 193",
      "season_number": 2026,
      "episode_number": 193,
      "runtime_minutes": 60,
      "network_or_streaming_service": "CNBC Europe"
    },
    {
      "genres": [],
      "runtime": "75 min",
      "show_id": 51281,
      "show_name": "Morning Live",
      "episode_id": 3769232,
      "air_datetime": "2026-09-29T09:30:00+01:00",
      "episode_link": "https://www.tvmaze.com/episodes/3769232/morning-live-8x85-episode-85",
      "episode_title": "Episode 85",
      "season_number": 8,
      "episode_number": 85,
      "runtime_minutes": 75,
      "network_or_streaming_service": "BBC One"
    },
    {
      "genres": [],
      "runtime": "60 min",
      "show_id": 8611,
      "show_name": "Loose Women",
      "episode_id": 3774921,
      "air_datetime": "2026-09-29T12:30:00+01:00",
      "episode_link": "https://www.tvmaze.com/episodes/3774921/loose-women-30x112-episode-112",
      "episode_title": "Episode 112",
      "season_number": 30,
      "episode_number": 112,
      "runtime_minutes": 60,
      "network_or_streaming_service": "ITV1"
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@tvmaze",
  "visibility": "public",
  "operation": "get_show",
  "version": 1,
  "input": {
    "show": "The Last of Us"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@tvmaze\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_show\",\n  \"version\": 1,\n  \"input\": {\n    \"show\": \"The Last of Us\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@tvmaze",
  "visibility": "public",
  "operation": "get_show",
  "version": 1,
  "input": {
    "show": "The Last of Us"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/tvmaze`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_show`: Get show. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `get_tv_schedule`: Get tv schedule. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-tvmaze https://api.fous.com/mcp/tools/tvmaze --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Plan viewing around upcoming broadcasts and streaming releases
- Track show schedules and episode details
- Compare episode runtimes across shows
- Organize shows by genre and status
- Review show ratings and premiere dates

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this TVmaze tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a TVmaze account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from tvmaze.com when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### What episodes are airing on a particular date?

Get tv schedule returns episodes in air-time order for a date and country, with optional streaming releases.

### What is a show’s schedule and status?

Get show returns a show’s schedule and status when given its name or TVmaze link.

### What episodes belong to a show?

Get show can return the full episode list, including specials when requested.

## Related

- [TMDB API](https://fous.com/tools/tmdb.md): TMDB returns movie and TV details, cast, trailers, releases, viewing services, scheduled upcoming movies, and up to 20 homepage trending titles; future episode details depend on published schedules.
- [IMDb API](https://fous.com/tools/imdb.md): IMDb returns movie, TV, person, episode, chart and Parents Guide details, including available weekly rank changes; missing details are null, and unaired or unrated episodes lack ratings.
- [AniList API](https://fous.com/tools/anilist.md): AniList helps users discover anime and track upcoming episodes, with local air times and streaming links when available; episode counts and schedules may be unavailable.
- [Crunchyroll API](https://fous.com/tools/crunchyroll.md): Crunchyroll provides anime streaming and release schedules, showing scheduled episodes for a selected week when available, plus public series details by name or link.
- [MyAnimeList API](https://fous.com/tools/myanimelist.md): MyAnimeList provides anime, manga, manhwa and light novel details, ratings, seasonal and top rankings; streaming follows its listings, and unannounced or unavailable details may be missing.
- [Netflix API](https://fous.com/tools/netflix.md): Netflix offers weekly global and country Top 10 rankings, all-time popularity rankings based on titles’ first 91 days, and title details with country availability that may lag.
- [Twitch API](https://fous.com/tools/twitch.md): Twitch returns channel profiles, live status, up to 10 broadcasts, top streams, viewer-ranked categories, up to 100 public videos/clips, and 1–30-day schedules; counts change.
- [JustWatch API](https://fous.com/tools/justwatch.md): JustWatch shows where movies and shows are available, including streaming, purchase, and cinema options, plus recent streaming arrivals and daily streaming charts based on its listings.
- [All Entertainment tools](https://fous.com/tools/category/entertainment)