Getting Started with our Real-Time API

Access real-time audience data with an HTTP GET request to our live API endpoints.

Our Real-Time API consists of data that is updated every three seconds, detailing what is happening on your site right now. There are two categories of real-time API endpoints detailed in the next two articles within this section: traffic data endpoints, and video engagement data endpoints (available only to organizations that use our Video Engagement add-on).

Rate limits

In order to prevent against API abuse we rate limit the amount of requests a user is allowed to submit. Our current rate limit is 200 requests per minute per host. Our suggested best practice is to call the endpoint within our rate limit, never directly embed your API calls into your production website code, and instead cache the results server-side to populate your custom widgets or dashboards. In addition, we cache queries for 3 seconds, so it's unnecessary to make requests more frequently than that.

There's a header in every response that says how many requests are remaining on the rate limit (X-RateLimit-Limit and X-RateLimit-Remaining).

Required parameters

Host: To be passed as a query parameter "host" in the URL. This is the Site ID associated with your Chartbeat account that you want to get data for, and the value of your _sf_async_config.domain variable in the Chartbeat tracking code for that site. If you are using one of our real-time video API endpoints, the host value is your site ID prepended with "video@". For example, host=[e-mail].

API Key: To be passed in the HTTP Header with "X-CB-AK". You can create and access your API key here 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/live/quickstats/v4/?all_platforms=1&host=<YOUR HOST>&limit=50&loyalty=1&metrics=account_type%2Cmedium%2Csource%2Ccampaign&now_on=1&types=1"

Next steps

The next page of this guide details all of our Real-Time API endpoints for retrieving traffic and page data.

If you're seeking out our Real-Time API for retrieving video engagement data, skip ahead to page 3.