Title: Conversions endpoint use and overview
Author: staff
Published: July 21, 2022
Last modified: June 1, 2026

---

 1. [The Parse.ly API](https://docs.parse.ly/api/)
 2. [Endpoints](https://docs.parse.ly/api/api-endpoints/)
 3. Conversions endpoint use and overview

#  Conversions endpoint use and overview

The Parse.ly Conversions API addresses two use-cases: First, to download detailed
URL-level conversion metrics for ad-hoc analysis (`/conversions/url`). Second, to
provide a top-converting content module on your site containing a list of URLs, 
filtered by metadata, and ranked by conversion metrics (`/conversions/url/top/`).
These endpoints follow all the same authentication, error, and formatting standards
specified in our [documentation](https://docs.parse.ly/api-endpoints/) and closely
follow the functionality or our [/analytics endpoint](https://docs.parse.ly/api-analytics-endpoint/).

## /conversions/url

Returns detailed conversion metrics for all of your URLs, broken down by all of 
your conversion labels. This API provides the most granular metrics on converting
content and is typically used to populate a data warehouse for ad-hoc analysis.

### Optional Parameters

| attribution_type | Determines which of our [attribution models](https://docs.parse.ly/conversions/) to use for computing conversion metrics. Either `linear`, `last_touch`, `last_post_touched`, or `first_touch`. Defaults to `last_touch` if not specified. | 
| conversion_type | One or more [conversion types](https://docs.parse.ly/conversions/) to use for computing conversion metrics. Using this filter will result in conversion metrics being calculated for all conversion labels of these types. Either `newsletter_signup`, `custom`, `lead_capture`, `link_click`, `subscription`, or `purchase`. Defaults to returning conversion label-level metrics for all conversion types if not specified. | 
| conversion_label | One or more of your custom [conversion labels](https://docs.parse.ly/conversions/). Defaults to returning conversion label-level metrics for all of your conversion labels if not specified. | 
| page_type | One or more page types to consider conversion from. Either `post` or `index`. Defaults to returning conversions across all page types if not specified. | 
| period_start | Start of date range to consider conversions from; see [Date/Time Handling](https://docs.parse.ly/api-date-time/) for formatting details. Defaults to 3 days ago. | 
| period_end | End of date range to consider conversions from; see [Date/Time Handling](https://docs.parse.ly/api-date-time/) for formatting details. Defaults to current date and time if not specified. The maximum difference between period_start and period_end is 15 days. | 
| pub_date_start | Publication filter start date; see [Date/Time Handling](https://docs.parse.ly/api-date-time/) for formatting details. This option is only available for posts. | 
| pub_date_end | Publication filter end date; see [Date/Time Handling](https://docs.parse.ly/api-date-time/) for formatting details. Defaults to current date and time if not specified. This option is only available for posts. | 
| url | A specific URL to return conversions metrics for. This should match the [canonical URL](https://docs.parse.ly/the-parsely-canonical-url/) for the page in question. Defaults to returning metrics for all URLs if none is specified. | 
| limit | Number of records to retrieve; defaults to `10`. Maximum is `2000`. | 
| 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 | (page_type=post only) Filter the current top posts by one or more authors. | 
| tag | (page_type=post only) Filter the current top posts by one or more tags. | 
| section | (page_type=post only) Filter the current top posts by a specific section. | 
| segment | (page_type=post only) Filter the current top posts by a specific segment. | 
| channel | (page_type=post only) Filter the current top posts by a specific channel (website or amp). | 
| campaign_id | (page_type=post only) Filter the current top posts by a specific campaign ID. | 
| campaign_medium | (page_type=post only) Filter the current top posts by a specific campaign medium. | 
| campaign_source | (page_type=post only) Filter the current top posts by a specific campaign source. | 
| campaign_content | (page_type=post only) Filter the current top posts by a specific campaign content. | 
| campaign_term | (page_type=post only) Filter the current top posts by a specific campaign term. |

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 `conversion_type`, `conversion_label`, `author`, and/or `tag` filters may
be specified by repeating the parameter (e.g. `\`?tag=report&tag=tesla&tag`=evs“).
Each parameter supports up to a maximum of five values.

## /conversions/url/top/

Returns a list of URLs sorted by conversion metrics. This is typically used to generate
front page or article page widgets featuring your top-converting content. **NOTE:**
In order to safely protect your API secret, you’ll want to pull this data in on 
your backend rather than making the API request on your frontend.

### Optional Parameters

| attribution_type | Determines which of our attribution models to use for computing conversion metrics. Either `linear`, `last_touch`, `last_post_touched`, or `first_touch`. Defaults to `last_touch` if not specified. | 
| conversion_type | One or more conversion types to use for computing conversion metrics. Using this filter will result in conversion metrics being aggregated across all of your conversion labels of these types. Either `newsletter_signup`, `custom`, `lead_capture`, `link_click`, `subscription`, `purchase`. Defaults to aggregating metrics across all conversion types if not specified. | 
| conversion_label | One or more of your custom conversion labels. Defaults to aggregating metrics across all of your conversion labels if not specified. | 
| page_type | One or more page types to consider conversions from. Either `post`, `sectionpage`, `frontpage`, or `index`. Defaults to returning conversions across all page types if not specified. | 
| period_start | Start of date range to consider conversions from; see Date/Time Handling for formatting details. Defaults to 14 days ago. | 
| period_end | End of date range to consider conversions 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. 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 | Either `conversions` or `converting_visitors`, if that feature is enabled; defaults to `conversions`. | 
| limit | Number of records to retrieve; defaults to `10`. Maximum is `2000`. | 
| 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 | (page_type=post only) Filter the current top posts by one or more authors. | 
| tag | (page_type=post only) Filter the current top posts by one or more tags. | 
| section | (page_type=post only) Filter the current top posts by a specific section. | 
| segment | (page_type=post only) Filter the current top posts by a specific segment. | 
| channel | (page_type=post only) Filter the current top posts by a specific channel (website or amp). | 
| campaign_id | (page_type=post only) Filter the current top posts by a specific campaign ID. | 
| campaign_medium | (page_type=post only) Filter the current top posts by a specific campaign medium. | 
| campaign_source | (page_type=post only) Filter the current top posts by a specific campaign source. | 
| campaign_content | (page_type=post only) Filter the current top posts by a specific campaign content. | 
| campaign_term | (page_type=post only) Filter the current top posts by a specific campaign term. |

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 `conversion_type`, `conversion_label`, `author`, and/or `tag` filters may
be specified by repeating the parameter (e.g. `?tag=report&tag=tesla&tag=evs`). 
Each parameter supports up to a maximum of five values.

Last updated: June 01, 2026