Real-Time API

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

Getting started with our Real-Time API

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 user 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 API key. 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: 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,

API Key: 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.