API Docs / Account

Your usage

Free keyLive and CompleteMCP: check_usage

Your key's plan, how many calls it has made today and this month, its limits and the data its plan reads.

ReturnsOne record about your key

Up toOne record

FreshLive, never cached

PlanEvery plan, the free key too

GEThttps://api.tvschedule.org/v1/usage

What it is for

Call this to see where a key stands without counting against it. It answers with the plan, the calls made today and this month across all your keys, the pace and allowance of the plan, when each counter resets, and which days of listings and statistics the plan reads.

It is the call a dashboard, a health check or an assistant makes first, so it can say what the key can do before it tries.

A usage meter

Show calls used against the allowance in your own admin page.

A health check

Confirm a key is active and on the plan you expect, at no cost.

Pacing a job

Read the limits and resets, then spread a large job to fit.

/v1/usagethen/v1/countries /v1/channels/{id}/schedule/{date}/v1/shows/search/{q}

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.

Your usage

Works on the free key

Your key

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

https://api.tvschedule.org/v1/usage

Not counted against 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/usage" \
  -H "X-API-Key: <your key>"

Parameters

None. The key is all it needs.

Returns

One record under data, with meta beside it.

Field	Type	Example	What it holds
`plan`	string	free	Your plan
`plan_name`	string	Free key	Your plan's name
`key_prefix`	string	tvs_live_7f3a	The start of the key used
`calls_today`	integer	0	Calls made today across all your keys, counted in UTC.
`calls_month`	integer	0	Calls made this calendar month across all your keys.
`limits`	object	{"per_minute":30,"per_day":200,"...	per_minute, per_day and per_month for your plan. A null means no limit of that kind.
`resets`	object	{"minute":1793299320,"day":"2026...	When the minute, the day and the month counters next start again, in UTC.
`window`	object	{"listings":"yesterday only","st...	In words, the listings days and the statistics window your plan reads.

Example answer

A real answer from our data, cut to three rows, so you can see the shape before you run anything.

200 OKhttps://api.tvschedule.org/v1/usage

{
    "data": {
        "plan": "free",
        "plan_name": "Free key",
        "key_prefix": "tvs_live_7f3a",
        "calls_today": 0,
        "calls_month": 0,
        "limits": {
            "per_minute": 30,
            "per_day": 200,
            "per_month": null
        },
        "resets": {
            "minute": 1793299320,
            "day": "2026-10-30T00:00:00Z",
            "month": "2026-11-01T00:00:00Z"
        },
        "window": {
            "listings": "yesterday only",
            "statistics": "none"
        }
    },
    "meta": []
}

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

PreviousMost repeated last week NextMCP tools