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
| type | One of posts, authors, sections, tags, referrers, channels, campaigns,segments |
Optional Parameters
| period_start | Start 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_end | End 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_start | Publication filter start date; see Date/Time Handling for formatting details. This option is only available for posts. |
| pub_date_end | Publication 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. |
| sort | Sort value; default is views (popularity). See Available Metrics for complete list of options |
| limit | Number of records to retrieve; defaults to “10”. |
| page | Page number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list. |
| callback | JSON-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_start | Start 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_end | End of date range to consider traffic from; see Date/Time Handling for formatting details. Defaults to current date and time if not specified. |
| limit | Number of records to retrieve; defaults to “10”. |
| page | Page number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list. |
| callback | JSON-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
| url | URL of post to fetch details on. This must be in canonical form, including “http://” scheme |
Optional Parameters
| period_start | Start 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_end | End of period to consider traffic from; see Date/Time Handling for formatting details. Defaults to current date and time if not specified. |
| callback | JSON-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
| meta | one of author, section, tag |
Optional Parameters
| period_start | Start 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_end | End of period to consider traffic from; see Date/Time Handling for formatting details. Defaults to current date and time if not specified. |
| pub_date_start | Publication filter start date; see Date/Time Handling for formatting details. |
| pub_date_end | Publication filter end date; see Date/Time Handling for formatting details. Defaults to current date and time if not specified. |
| sort | Sort value; default is views (popularity). See Available Metrics for complete list of options |
| limit | Number of records to retrieve; defaults to 10. |
| page | Page number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list. |
| callback | JSON-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: August 16, 2023