API Docs / Shows

Where a show airs

Live and CompleteFree key: empty with a noteMCP: show_airings

Where and when a show airs in the days ahead, on every channel, first runs and repeats told apart.

ReturnsAirings, soonest first

Up toUp to 7 days ahead

FreshUp to 15 minutes old

PlanLive and Complete

GEThttps://api.tvschedule.org/v1/shows/{id}/airings

What it is for

Give a show id and get each upcoming airing: the channel, when it starts and ends in UTC, the title as listed, the episode where matched, and whether it is new, live or a repeat. Add country to keep to one market.

This is the "when is it on next" call, and the heart of reminders and watch lists.

Reminders

Tell a user before the next new episode starts.

Watch lists

Show where each saved show airs this week.

"When is it on"

An assistant answers with the next showing and the channel.

/v1/shows/{id}/airingsthen/v1/shows/{id}/pattern /v1/channels/{id}/schedule/{date}/v1/shows/{id}

Try it

Calls the real API with your key and shows the answer below. Your key stays in this browser and fills in on every docs page.

Where a show airs

Needs Live or Complete

Your key

No key yet? Get a free key. It fills in here by itself once made.

idrequired country days

https://api.tvschedule.org/v1/shows/sh_sdkgxsfs/airings

Uses 1 call from your plan.

Calling

Code

Built from the form above, with your key in place. The language you pick is remembered.

curl "https://api.tvschedule.org/v1/shows/sh_sdkgxsfs/airings" \
  -H "X-API-Key: <your key>"

Parameters

Name	In	Type	Example	What it does
`id`required	path	string	sh_sdkgxsfs	The show id, from show search.
`country`	query	string	GB	Only airings in this country, as a two-letter code.
`days`	query	integer	7	How many days ahead to cover, within your plan. 1 to 7

Returns

A list under data, with meta.count beside it.

Field	Type	Example	What it holds
`channel`	string	ch_jw83a3xg	The channel id it airs on.
`start`	datetime	2026-10-30T19:30:00Z	When it starts, UTC.
`stop`	datetime	2026-10-30T20:00:00Z	When it ends, UTC.
`title`	string	EastEnders	The programme title
`episode`	object	{"show_id":"sh_e29nzc1x","season...	The show and episode where matched: show_id, season, number
`flags`	object	{"new":true,"live":false,"repeat...	new, live and repeat, each true or false.

Example answer

The example answer appears here as soon as this endpoint's data is live. Run above shows a real answer with your key.

Errors

Status	Code	When	What to do
401	`unauthorized`	No key was sent, or it is not an active TV Schedule key.	Send it as Authorization: Bearer <key> or X-API-Key. Your keys are in your account.
403	`upgrade_required`	Your plan does not read this: a day outside its window, or an endpoint on Live and Complete.	The message names the plan that does. Upgrade on the same key at /pricing.
404	`not_found`	No show has that id.	Take ids from the search and directory endpoints. Every address is listed in these docs.
400	`bad_request`	A value is the wrong shape: a date that is not YYYY-MM-DD, a two-character search, a key sent in the address.	Fix the value the message names and send it again.
422	`unknown_parameter`	A query parameter this endpoint does not take.	The message lists the ones it does take.
429	`rate_limited`	Faster than your plan's pace per minute.	Wait for Retry-After seconds. The X-RateLimit headers show where you are.
429	`quota_exceeded`	Your plan's allowance for the day or month is used.	It resets at the time in the message, or upgrade for a bigger allowance.
500	`server_error`	Something went wrong on our side, or the data was out of reach for a moment.	Try again in a minute. It has been logged, and /status shows the state of the service.

Next calls

PreviousOne show NextPatterns guide