API Best Practices

    • Do not share your OAuth2 token since calls are metered and billing is based on usage. Sharing could lead to higher charges, rate-limiting and blocking.
    • Do not add the API token to a client side deployment or webpage since it can be extracted by any user.
    • We almost always issue Read-only tokens so there is only 1 permission level which allows calling our API to get data.


  2. Pagination: Recommend to not request more than 25 articles, 50 influencers and 50 conversations per call. Pagination is provided to make subsequent calls for scroll down scenarios. Below these limits, per call data size and bandwidth requirements are easily manageable, even on mobile devices.
  3. Timeouts: For live scenarios, provide UI/UX to the user to retry in case of timeouts. This is rare but can happen for certain non-standard queries.
  4. Handling failures: For live scenarios, providing UI/UX to retry in case of failures. For batched scenarios, keeping a cached copy from the previous call can be used to handle this. Usually, the only reason for failures, outside of timeouts, is network related problems or our site being down. We have monitoring and redundancy so such situations are extremely rare and resolved quickly.
  5. No (0) documents returned: This is for cases where the query matches no document in our platform. Showing 0 documents returned and having the user try other queries is standard and recommended.
  6. In offline scenarios, for e.g. posting articles to WordPress after manual/automated review and editing, minimum 30-minutes between calls for a given topic is recommended. Articles being updated within 30-minutes is extremely rare.
  7. Auto-complete is highly recommended since relevance for topics from the drop-down list, in general, is much higher than free-form search. It also provides a better user experience by providing options to the user.
  8. Please do not call the API in undocumented ways. Such calls may work for now but can stop working at any point of time leading to your application breaking.

Leave a Reply