Chartbeat API

Chartbeat collects various metrics about each visitor on your site. Some of this is reported basically raw (like number of readers on an article), and some data is mashed up and modified before being reported (like understanding that a visitor that came from Twitter is ‘social’). But in the end, it’s all information about visitors, aggregated at the site or page level. For example, ‘there are 100 concurrent visitors on page X, 12 of them are new to your site, 30 are currently reading or writing, etc.’

Our REST API allows users to uncover this information. Just make an HTTP GET request to an API endpoint and it’ll return the data encoded in JSON.

NOTE: All date-time objects are in Eastern Standard Time, NOT UTC.

Our API is split into two categories based on how the data updates: Live and Historical. Our Live API consists of data that is updated every three seconds, detailing what is happening on your site right now. On the other hand, our Historical API consists of data that is more persistent and is a summary of what users are doing over time spans.


Our Live API lets you find out what's happening on your site right now. You can discover the pages that have the most visitors, the amount of people engaging on a specific page, or specific information about your most recent visitors.


Our Historical API lets you analyze historical data on your site. You can discover the daily max of tweets or Facebook likes in the past week, the hourly traffic to your site over the past day, or the average user engagement in the past month.


Our documentation is coupled with an API explorer. Start playing with our APIs right now!

If you want to check out some examples of how people have used the API, check out Chartbeat Labs.


All of our APIs are versioned independent of one another. Currently all the Live APIs are at version three as indicated by the v3/ at the end of the endpoint URL. The Historical APIs are all at their first version, and therefore bare no version number at the end of their URL. As we continue to release new updates to our APIs we will version them by adding a component to the url with v[version_number]/. e.g. If we were to create a version two of the historical social stats endpoint, it would be historical/social/stats/v2/.


You must be an active subscriber of chartbeat to use the API. If you're not already, sign up.

Rate Limiting

In order to prevent against API abuse we rate limit the amount of requests a user is allowed to submit. Currently we have not publicized the limit, but for any normal use case the limit should not be a problem. Also, we cache queries for 3 seconds, so it's wasteful and unnecessary to make more frequent requests.

API Terms and Conditions

Please review the API Terms and Conditions before use.