Frequently Asked Questions

Frequently asked questions about the API.


Stream API



Do you support JSONP?

Yes; see the JSONP section for more information.

Can I create or modify a stream's configuration via an API?

All stream creation and configuration changes must be made within the Experiences UI. The API does not support the programmatic creation and configuration of streams.

What happens when a stream is reset?

When a user resets a stream within Experiences, the following things happen:

  1. All content is removed from the stream. The Stream API will return no data until new data is sourced and approved (either automatically via rules or manually).
  2. Counts are reset to zero. This includes counts in the Stream Meta API including approved, pending, and rejected, along with topic counts. The exception is...
  3. Activity counts (counts over time) in the Stream Meta API are not reset. They persist.

Stream API

Are entity responses standardized?

The API returns the same JSON provided by the social networks with minimal modifications. Because of this, the API response is not standardized across networks.

Do you provide documentation for each kind of entity response (Tweet, Instagram post, etc)?

Since the API returns largely unmodified JSON, we recommend you consult the API documentation provided by each social network relevant to the entities you are displaying:

In addition, the Displaying Status Entities page includes some tips and tricks along with sample feeds that you'll want to check out.

What do you mean by largely unmodified?

We do add a couple of useful things to each entity:

How do I render Twitter media?

This is explained on the Displaying Status Entities page.

What happens if an entity is rejected?

If an approved entity is later rejected, it will be removed from the API response for future requests. Past requests that contained the now-rejected entity will not be updated to reflect the rejection; rejection notifications are not available via the API. Requests made after the rejection will not contain the rejected content.

Is pending or rejected content available?

The Stream API returns only approved content. Pending and rejected content are not available via the API.

In general, metadata (e.g. data returned by the Stream Meta API, Leaderboard APIs, and the Compare API) is derived from approved content, but pending, rejected, and total counts (not content) are available in the Stream Meta API.

In practice, approved and total counts are the most frequently used.

How is content sorted in the API response?

By default, content is returned in the order it was approved (more recently approved content on top). In most cases, this will chronological or close-to-chronological creation order, but in the case of manual moderation the order may differ significantly from creation order.

Two exceptions apply:

How often can I make requests to the API?

We recommend making API requests no more than once every 15 seconds per user.

For example: when a user first loads the page, make a request for content; 15 seconds after that, make another request for content, etc.

Is it possible to pass multiple values to the network parameter, (e.g. twitter,facebook)?

No. The network parameter supports a single network only.

How should I render retweets?

Rendering retweets does require some attention. The Displaying Status Entities guide has some tips on how to handle this.

Why don’t I get back as many items as I requested (using limit)?

This can happen for one of two reasons:

  1. There simply isn't enough approved content! For instance, if there are 25 approved items and you request limit=50, a maximum of 25 items will be returned.
  2. Deduplication. Very occasionally, a stream's approved queue can contain duplicate items. Typically this only occurs with Instagram content; when a stream sources two Instagram hashtags, it's possible for one photo that contains both hashtags to be sourced twice, introducing a duplicate. These duplicates are filtered out in the API response, so you should never see them. However, this deduplication process can reduce the number of returned items; for example, it's possible to receive 99 items when you requested limit=100 if there is one duplicate pair.

Because of these reasons, make sure your application's display does not depend on a certain number of items being returned.

Can I retrieve content from a stream that contains certain keywords? What about content from different accounts?

The keywords and from parameters might be what you're looking for! Check out the Stream API documentation for more info.

How do I render linked media such as images and videos?

The Displaying Status Entities guide has some tips on how to handle this.

Facebook images are displaying in low resolution. How do I render larger images from Facebook items?

The Displaying Status Entities guide has some tips on how to handle this.

How do I render Facebook avatars?

The Displaying Status Entities guide has some tips on how to handle this.

How do I render Twitter links correctly (without displaying URLs)? How do I link hashtags to Twitter search and handles to Twitter accounts?

The Displaying Status Entities guide has some tips on how to handle this.

In short: to make this easy, Twitter provides many open-source client libraries to correctly display and link statuses:


How are Top Retweets calculated?

Both the Top Shares Leaderboard API and Stream Meta API return "Top Retweets" - a list of the most retweeted content in a stream. Top Retweets are calculated the same way for both APIs:

The Top RT section of the Stream Meta API requires that an item have at least 3 retweets before it is featured.

Question not answered?

If you've got a question or a suggestion, don't hesitate to contact the Digital Producer for your project. If you aren't working with a Digital Producer, shoot an email to Support. We look forward to hearing from you!