LogoLogo
Help CenterStatusContact
  • Chartbeat Documentation
  • Implement Tracking
    • Standard Websites
      • Adding chartbeat.js to Your Site
      • Customize Tracking Settings
      • Tracking Virtual Page Change
      • User Subscriber Status
      • Alternative Site Integrations
      • Integration QA Steps: Website
      • Additional Page Metadata
    • Google AMP
      • Chartbeat Code for AMP
      • AMP Configuration Variables
      • Alternative AMP Integration
      • Integration QA Steps: AMP
    • Mobile App SDKs
      • Intro to Mobile App Tracking
      • Android SDK
      • iOS SDK
      • Integration QA Steps: Mobile Apps
  • Feature Integrations
    • Headline and Image Testing
      • Adding chartbeat_mab.js to Your Site
      • Image Compatibility
      • Flicker & Flicker Control
      • mab.js Specifications
      • Integration QA Steps: Headline and Image Testing
    • Video Engagement
      • Adding chartbeat_video.js to Your Site
      • Supported OVP Integrations
      • Custom Player Integration SDK
      • Configure Video Tracking Settings
      • Integration QA: Video Tracking
    • Conversion
      • Adding subscriptions.js to Your Site
      • Conversion Events
      • Integration QA Steps: Conversion
      • Supported Conversion Flows
  • API Docs
    • Real-Time API
      • Getting Started with our Real-Time API
      • Traffic Data
      • Video Engagement Data
    • Historical API
      • Getting Started with our Historical API
      • One-time Queries
      • Recurring Queries
      • Metrics, Dimensions, and Filters
    • Headline Testing API
      • Getting Started with our Headline Testing API
      • Raw Data
      • Summary Report
      • Variant Report
    • Conversion API
      • Getting Started with our Conversion API
      • Top Articles
    • Data Lab API
      • Getting Started with Data Lab API
  • Help Center
  • Contact Support
  • Datastream Docs
  • Back to Chartbeat.com
Powered by GitBook
On this page
  • Retrieving Results for Event Counts
  • Required API Parameters
  • Optional API Parameters

Was this helpful?

  1. API Docs
  2. Conversion API

Getting Started with our Conversion API

Get familiar with our Conversion API to fetch the top articles that drove a given event.

PreviousConversion APINextTop Articles

Last updated 4 months ago

Was this helpful?

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 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: <YOUR API KEY>" "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=

Sort by Event Type

sort_event_type=

Row limit

limit=

The maximum number of distinct articles to return.

Optional API Parameters

Parameter name
Syntax
Description

Start Date

start=

End Date

end=

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.

NOTE: Your API key should no longer be set as a query param; instead.

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.

If using a start/end date, including a timestamp. The format of the timestamp should be (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).

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 (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).

API key here
pass it in the HTTP header
Event type
ISO 8601 compliant
ISO 8601 compliant