API Basics


To get the most out of the API, you should familiarize yourself with the following terms and concepts:


Experiences is a Spredfast product that, among other things, enables users to create streams for use in visualizations. The API focuses on streams since they are the basic data source for visualizations, and API developers are most interested in leveraging this data to create their own visualizations.


A stream is a curated collection of social posts that updates in real time. Streams are created and configured within the web-based Experiences application. They have three primary configuration areas: sources, rules, and topics.

Sources determine what content to include in the stream. Rules dictate what content to exclude, although sometimes they are be used to automatically approve content too. Content from various social networks is aggregated into a stream - usually one per cultural topic - then run through rules in real-time. Content is sorted into three queues: approved, pending, and rejected. Approved content is surfaced in these APIs; as new content is approved, it's immediately available in the API. Topics count specific mentions within a stream (useful for ranking items or for counting votes in a social poll).

Streams are owned by users; to make API requests, one must know a stream's name and the stream owner's username.

Streams are enabled by default, meaning that content flows into the stream as soon as sources are added. Sources can be disabled, pausing content ingestion while retaining current content, or they can be reset, removing all content from the stream while maintaining all settings.

Lots more information about stream configuration can be found at the Support Center (login required). This API documentation generally assumes that streams have already been configured, but sometimes the structure of the API dictates how streams must be set up. In any case, the Spredfast Customer Success teams are there to guide you through the implementation process.


Entity is a generic word for a social post. Tweets, Facebook posts, Instagram items, etc. are all entities.



Unless otherwise noted please use this domain. tweetriver.com is still a valid domain until further notice, but new implementations should utilize api.massrelevance.com.

Example URL: http://api.massrelevance.com/MassRelDemo/kindle.json


api.massrelevance.com supports requests over SSL. Use https as the protocol instead of http.

Example URL: https://api.massrelevance.com/MassRelDemo/kindle.json

Status Codes

When possible the API returns valid response codes:

However, the API does not support "304 Not Modified" responses.

Encoding (gzip)

The API can gzip responses. Where possible, use gzip! It improves performance.

To use gzip, ensure the HTTP client has the Accept-Encoding: gzip header added to requests.


Most of the json endpoints support JSONP requests. Use callback or jsonp query parameter on json endpoints.

Example URL: http://api.massrelevance.com/MassRelDemo/kindle.json?callback=foo