List subscription events

get

https://{subdomain}.supercast.com/api/v1/subscribers/events

Lists subscription lifecycle events for the current entity, newest first. Use this to build
an audit trail of activations, cancellations, charge failures and plan changes.

Beware of the date-parameter inconsistency on this endpoint. It accepts three
time filters that do not agree on a format:

Parameter	Format
`updated_since`	ISO 8601 string, e.g. `2026-08-01T00:00:00Z`
`start_date`	Integer Unix epoch seconds, e.g. `1754006400`
`end_date`	Integer Unix epoch seconds, e.g. `1756684800`

start_date and end_date are passed through Time.at(value.to_i), so a non-numeric value
silently becomes 0 (1970-01-01) rather than raising. updated_since validates its input
and returns 400 on a malformed value.

start_date / end_date filter on the event's created_at, and both are inclusive.

Required scope: public.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

channel_subdomain

string

Selects which channel or network the request acts on.

This applies to every endpoint in this API, not only GET /episodes. Its requirement
depends on what the access token's resource owner is:

Channel token — ignored. The token already identifies the channel.
Network token — optional. Omit it to act on the network itself; supply the subdomain
of one of the network's channels to act on that channel instead. An unrecognised subdomain
returns 400.
User or superapp token — required. The token is not bound to an entity, so the
target must be named on every request. Omitting it returns 400; naming an entity the user
does not manage returns 403.

The X-CHANNEL-SUBDOMAIN header takes precedence over this parameter. A legacy subdomain
query parameter is also still accepted as a fallback.

updated_since

date-time

Only return records updated at or after this time — an ISO 8601 timestamp.

The comparison is inclusive (>=), so a consumer polling for changes can pass the newest
updated_at it has already seen without missing records written in the same second. Expect
to see the boundary record returned again and deduplicate on id.

On endpoints whose payload is assembled from more than one table, the filter matches a change
to any of those tables — see the individual endpoint description for which.

A value that is not valid ISO 8601 returns 400. A blank value is treated as absent.

page

integer

≥ 1

Defaults to 1

1-based page number. Pagination metadata is returned in the Link, X-Total, X-Per-Page and X-Page response headers.

per_page

integer

≥ 1

Defaults to 30

Number of records per page.

event_type

string

enum

Return only events of this type.

start_date

int64

Only return events created at or after this time. Unix epoch seconds, not ISO 8601 — unlike updated_since on this same endpoint.

end_date

int64

Only return events created at or before this time. Unix epoch seconds, not ISO 8601 — unlike updated_since on this same endpoint.

Headers

X-CHANNEL-SUBDOMAIN

string

Header form of channel_subdomain, and the preferred one — it takes precedence over both the channel_subdomain and legacy subdomain query parameters. See channel_subdomain for when a value is required.

Responses

200A page of subscription events.

400The request was malformed — a required body key was missing, or a supplied channel_subdomain did not resolve to an entity, or a filter parameter such as updated_since was not parseable.

401No access token was supplied, or the token is invalid, expired, or revoked. Also returned when the token lacks the scope the endpoint requires.

403The token is valid but not permitted to act here — the requesting user does not manage the named entity, or the caller's IP address is on the channel's block list.

404No record matched, or the record exists but does not belong to the entity in scope.

422The request was well-formed but could not be completed — typically model validation failure. errors maps each rejected attribute to its messages.

500An unexpected error occurred. The failure is reported to Supercast automatically.