# 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/workflows/tvmaze
- Handle: `@tvmaze`
- Category: [Entertainment](https://fous.com/workflows/category/entertainment)
- Source website: https://tvmaze.com
- Last verified: Sep 29, 2026
- Fous is not affiliated with TVmaze.

## Methods

### Get show

Operation `get_show`, version 1. 1 credit per call.

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 call.

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 |  | Episode runtime as text, such as 30 min. |
| `episodes[].show_id` | integer or null |  | TVmaze show ID. |
| `episodes[].show_name` | string or null |  | Show name. |
| `episodes[].episode_id` | integer or null |  | TVmaze episode ID. |
| `episodes[].air_datetime` | string or null |  | Air date and time in ISO 8601 with an offset, in the service timezone when available. |
| `episodes[].episode_link` | string or null |  | TVmaze episode page. |
| `episodes[].episode_title` | string or null |  | Episode title. |
| `episodes[].season_number` | integer or null |  | Season number. |
| `episodes[].episode_number` | integer or null |  | Episode number. |
| `episodes[].runtime_minutes` | integer or null |  | Episode runtime in minutes. |
| `episodes[].network_or_streaming_service` | string or null |  | Broadcast network or streaming service. |

## Quick start

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_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.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

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=120) 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.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_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);
```

Or describe the data in plain language: send `{"api":"@tvmaze","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## 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

### Is Fous affiliated with TVmaze?

No. Fous is not affiliated with TVmaze. This workflow reads the public tvmaze.com website and returns its data.

### How much does it cost?

Each run costs 1 credit. 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; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check 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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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 workflows](https://fous.com/workflows/category/entertainment)