Referrers endpoint use and overview

GET /referrers/(referrer_type)

Return a list of the top referrers for a referrer type. This can be either an overall number, or a number restricted to a specific domain.

referrer_type One of social, search, other, internal

section	Section to restrict this query to.
tag	Tag to restrict this query to.
domain	domain to restrict this query to.
period_start	Start of date range to consider traffic from; see Date/Time Handling for formatting details. Defaults to 3 days ago.
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. The maximum difference between period_start and period_end is 90 days.
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.
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.

Return a list of the top posts, authors or sections referrered to.

referrer_type	One of `social`, `search`, `other`, `internal`
meta_type	One of `posts`, `authors`, `sections`, `tags`

section	Section to restrict this query to.
domain	domain to restrict this query to.
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.
pub_date_end	Publication filter end date; 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.

Returns a list of posts falling under the specified author or section.

referrer_type	One of `social`, `search`, `other`, `internal`
meta_type	One of `author`, `section`, `tag`
meta_value	the value for this meta type

domain	domain to restrict this query to.
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.
pub_date_end	Publication filter end date; 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.

Return a list of the top referrers for a given url.

url	the url to get referrer details for

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.
callback	JSON-P callback, a JavaScript function name that will be used to wrap the JSON response.

Last updated: November 12, 2025