List visit rollups

get

https://{subdomain}.supercast.com/api/v1/analytics/visits

Lists pre-aggregated visit rollups for the current entity, newest bucket first. A visit
is a first view of one of the entity's public pages by a given browser; repeat views within
the same fingerprint window are not counted again.

Each row is a time bucket, not a single visit. count is the number of visits in the
bucket, and country, referrer and the four utm_* attributes are breakdown objects
mapping an observed value to its count within that same bucket. Their counts sum to count
only where every visit carried a value for that dimension — an absent UTM parameter is not
recorded, so a breakdown may sum to less.

Pair this with GET /analytics/conversions, which is the identical shape for subscriptions
started, to compute a conversion rate per bucket, section or campaign.

For a network token this returns the rollups of the network and all of its channels. For
a channel token it returns that channel's own.

This endpoint does not support updated_since, despite the blanket statement in the
introduction above. These rows are immutable time buckets: one is written when its window
closes and is never modified afterwards, so an updated_since filter would either return
everything or nothing and mean neither. Use from and to, which filter on the bucket's
own timestamp, instead. Because buckets are never rewritten, a window that has already
closed is stable and safe to cache.

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.

from

date-time

Only return records at or after this time — an ISO 8601 timestamp, inclusive (>=).

Used by the endpoints that cannot support updated_since because their rows carry no
updated_at column. It filters the endpoint's own time column, which that operation's
description names (occurred_at for churn events, timestamp for the analytics rollups).

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

date-time

Only return records at or before this time — an ISO 8601 timestamp, inclusive (<=).

The upper bound counterpart to from, filtering the same column. Because both ends are
inclusive, a record landing exactly on the boundary is returned by an adjacent window too;
deduplicate on id when paging through consecutive ranges.

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.

sort

string

enum

Defaults to timestamp

Column to order the page by. Ties are broken by id, so paging through the collection is stable and a record cannot appear on two pages or be skipped between them. The breakdown objects (country, referrer, the utm_* attributes) are not orderable. A value outside the list falls back to the default rather than returning 400.

Allowed:

direction

string

enum

Direction to read sort in — asc or desc.

The default is per endpoint: it is whatever ordering that collection already returned before
it became sortable, and the endpoint's own sort parameter names it. Anything other than
asc or desc falls back to that default rather than returning 400.

It applies to the id tiebreaker as well as to sort, so reversing the direction reverses
the whole page rather than only its first key.

Allowed:

section

string

enum

Return only rollups recorded against this part of the site. landing_page is the entity's public signup page and is the default a visit is recorded under; newsletter is a public newsletter post, in which case content_ref names the post.

Allowed:

content_ref

string

Return only rollups for one specific piece of content, identified by the same "<class>_<id>" string the rows carry — e.g. Post_5521. Matched exactly. Rollups for the entity as a whole rather than a single item have a null content_ref and are not returned when this filter is set.

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

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.