Skip to content

API: Analytics endpoint use and overview

GET /analytics/(type)

Returns a list of posts, authors, sections, tags, or channels depending on the specified type. This is typically used to generate front page or article page widgets featuring your “Most Popular” content. Use analytics-detail to retrieve drill-downs to posts for “authors” and “sections” listings.

If you would like to retrieve video data from the /analytics endpoint, please see Video Analytics for the requirements and subset of supported parameters.

Path Arguments

typeOne of posts, authors, sections, tags, referrers, channels, campaigns,segments

Optional Parameters

period_startStart of date range to consider traffic from; see Date/Time Handling for formatting details. Defaults to 3 days ago, limited to most recent 90 days.
period_endEnd of date range to consider traffic from; see Date/Time Handling for formatting details. Defaults to current date and time if not specified.
pub_date_startPublication filter start date; see Date/Time Handling for formatting details. This option is only available for posts.
pub_date_endPublication filter end date; see Date/Time Handling for formatting details. Defaults to current date and time if not specified. This option is only available for posts.
sortSort value; default is views (popularity). See Available Metrics for complete list of options
limitNumber of records to retrieve; defaults to “10”.
pagePage number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list.
callbackJSON-P callback, a JavaScript function name that will be used to wrap the JSON response. The API also supports Cross-Origin Response Sharing.
author(Posts Only) Filter the current top posts by one or more authors.
tag(Posts Only) Filter the current top posts by one or more tags.
section(Posts Only) Filter the current top posts by up to five sections.
segment(Posts Only) Filter the current top posts by a specific segment.
channel(Posts Only) Filter the current top posts by a specific channel (website, amp, or fbia).
campaign_id(Posts Only) Filter the current top posts by a specific campaign ID.
campaign_medium(Posts Only) Filter the current top posts by a specific campaign medium.
campaign_source(Posts Only) Filter the current top posts by a specific campaign source.
campaign_content(Posts Only) Filter the current top posts by a specific campaign content.
campaign_term(Posts Only) Filter the current top posts by a specific campaign term.
campaign_key(Campaigns Only) Filter the campaign overview by a specific key (id, medium, source, content, term). Defaults to id.

The maximum pagination limit is 2000 records. You will receive an error from the API if you attempt to retrieve past record 2000 through any combination of page and limit.

Multiple author or tag filters may be specified by repeating the parameter (e.g. ?tag=report&tag=tesla&tag=evs). Each query supports a maximum of five author and five tag values.

GET /analytics/videos

Returns a list of videos. This is typically used to generate video queues of your “Most Popular” videos.

This endpoint will only return videos with metadata submitted through the API Metadata Endpoint.

Optional Parameters

period_startStart of date range to consider traffic from; see Date/Time Handling for formatting details. Defaults to 3 days ago, limited to most recent 90 days.
period_endEnd of date range to consider traffic from; see Date/Time Handling for formatting details. Defaults to current date and time if not specified.
limitNumber of records to retrieve; defaults to “10”.
pagePage number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list.
callbackJSON-P callback, a JavaScript function name that will be used to wrap the JSON response. The API also supports Cross-Origin Response Sharing.

The maximum pagination limit is 2000 records. You will receive an error from the API if you attempt to retrieve past record 2000 through any combination of page and limit.

GET /analytics/post/detail

Returns the post’s metadata, as well as total views and visitors in the metrics field. By default, this returns the total pageviews on the link for the last 90 days.

Query Parameters

urlURL of post to fetch details on. This must be in canonical form, including “http://” scheme

Optional Parameters

period_startStart of period to consider traffic from; see Date/Time Handling for formatting details. Defaults to 90 days and is limited to the most recent 90 days.
period_endEnd of period to consider traffic from; see Date/Time Handling for formatting details. Defaults to current date and time if not specified.
callbackJSON-P callback, a JavaScript function name that will be used to wrap the JSON response. The API also supports Cross-Origin Response Sharing.

GET /analytics/(meta)/(value)/detail

Returns a list of posts falling under the specified author, section or tag. This is typically used in one of two scenarios. On its own, it can be used to enrich article pages with “Most Popular Posts by this Author” and section pages with “Most Popular Posts in this Section”. In combination with /analytics, it can be used to implement a drill-down — first, you retrieve a list of most popular authors with that endpoint, then you drill into the posts for one specific author with this endpoint.

Path Arguments

metaone of author, section, tag

Optional Parameters

period_startStart of period to consider traffic from; see Date/Time Handling for formatting details. Defaults to 2 weeks and is limited to the most recent 90 days.
period_endEnd of period to consider traffic from; see Date/Time Handling for formatting details. Defaults to current date and time if not specified.
pub_date_startPublication filter start date; see Date/Time Handling for formatting details.
pub_date_endPublication filter end date; see Date/Time Handling for formatting details. Defaults to current date and time if not specified.
sortSort value; default is views (popularity). See Available Metrics for complete list of options
limitNumber of records to retrieve; defaults to 10.
pagePage number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list.
callbackJSON-P callback, a JavaScript function name that will be used to wrap the JSON response. The API also supports Cross-Origin Response Sharing.

The maximum pagination limit is 2000 records. You will receive an error from the API if you attempt to retrieve past record 2000 through any combination of page and limit.

Last updated: October 29, 2024