Rate Limit

The Otter API uses a credit allocation system to ensure fair distribution of capacity. Each IP is allocated 10,000 credits per hour. You can check the status of your credits with the following call:

http://otter.topsy.com/credit.json

In addition, each request contains rate limit information in the HTTP response headers.

Cost of API calls

Unless otherwise noted, an API call deducts 1 credit from your allocation. Search based API calls (/search, /searchcount, /authorsearch, /profilesearch) have a significantly higher computational cost on our backend, and deduct 10 credits per call.

Example HTTP Response Headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 2498
X-RateLimit-Reset: 1250791200

Paging Limits

All calls that take list parameters limit perpage to 50 and page to 10. This gives you access to top 500 items on any list.

Client Identification

We request that you identify your application or service via the User-Agent HTTP header. This value should be the url to your service or application. This is not mandatory, but when under heavy load, we will give preference to clients that identify themselves. It is also possible to identify via X-Topsy-UA HTTP header, if modifying the User-Agent header is not possible.

Higher grade access

We plan to support higher grade of access in the future. If you need this, please contact us.