# Getting Started with our Conversion API This section contains information on how to make requests to Chartbeat’s Top Converting Articles API endpoint, allowing you to fetch the top articles that drove a given event (e.g. subscriptions) for a specific time range. Counts are assigned *per attributed path.* For example, you can ask, "What were my top 10 articles over the last 3 hours that drove subscriptions?" ### Retrieving Results for Event Counts The Top Converting Articles API only provides Last Touch attribution for event categories that include a `Shown` event. For categories that do not include a `Shown` event, all conversions have a null attribution path; this means that you will see a count of total conversions for the selected event category, where conversions includes the total number of `Complete` events for the event category specified. ### Required API Parameters **API Key**: To be passed in the HTTP Header with "X-CB-AK". You can create and access your [**API key here**](https://chartbeat.com/publishing/settings/api-keys/) under your account settings. Make sure to select an API key that has access to all calls for your domain. #### Example CURL request `curl --header "X-CB-AK: " "https://api.chartbeat.com/milkyway_dashboard/v1/top_articles_by_event_type?host=YOUR_HOST.com&start=2024-01-01&end=2024-01-02&tz=America/New_York&limit=10&sort_event_type=paywall_complete"` | Parameter name | Syntax | Description | | -------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Host name | `host=` | The site you are querying (host is usually your website's root domain, e.g. `host=site.com`). | | API Key (*see note*) | `apikey=` | **NOTE**: Your API key should no longer be set as a query param; instead. [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/conversion-api/getting-started-with-our-conversion-api#required-api-parameters) | | Sort by Event Type | `sort_event_type=` | [Event type](https://docs.chartbeat.com/cbp/feature-integrations/conversion/conversion-events) used to sort articles. Use a combination of the event category name (e.g. `paywall`, `registration,` `newsletter_signup, download` - *see full list below*) and the action (`shown`, `start`, `complete`, or `cancel`) in the format `categoryname_action`. (e.g.`registration_complete`). **Note that these are case sensitive.** One value accepted. | | Row limit | `limit=` | The maximum number of distinct articles to return. | ### Optional API Parameters | Parameter name | Syntax | Description | | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Start Date | `start=` | If using a start/end date, including a timestamp. The format of the timestamp should be [ISO 8601 compliant](https://www.iso.org/iso-8601-date-and-time-format.html) (e.g. `2023-05-11T20:00:00Z`, i.e. a UTC timestamp) or if you want to query in a different time zone (e.g. `2013-05-11T20:00:00+07:00`). | | End Date | `end=` |

The API group event counts for articles by the hour. Set this argument to be the ending hour. This is an exclusive bound so the API will return counts at times less than the end parameter.

If using a start/end date, including a timestamp. The format of the timestamp should be ISO 8601 compliant (e.g. 2023-05-11T20:00:00Z, i.e. a UTC timestamp) or if you want to query in a different time zone (e.g. 2013-05-11T20:00:00+07:00).

| To query for all events received on May 11, 2023 from 20:00:00 to 22:59:59 (i.e. not including events received at 23:00:00 or later), you would set `start=2023-05-11T20:00:00Z&end=2023-05-11T23:00:00Z`. To query data for a single day, you would set `start=2023-05-11T00:00:00Z&end=2023-05-11T23:59:59Z`. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.chartbeat.com/cbp/api/conversion-api/getting-started-with-our-conversion-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.