Managing your API rate limit

January 3, 2012

We make our APIs available for free for non-commercial use to developers who are interested in building music applications on top of our platform.  These API methods are subject to rate limits. In general, non-commercial users of our API can expect a rate limit of around 120 calls per minute. This may vary depending upon overall system activity. If we are under a light load we may increase the limit associated with your API key and conversely, if we are under heavy load we may reduce that limit. You can discover what your current rate limit and activity is by inspecting the response header that is returned with each API method call. There are three fields in the header associated with rate limits:

  • X-RateLimit-Limit - the current rate limit for this API key
  • X-RateLimit-Used - the number of method calls used on this API key this minute
  • X-RateLimit-Remaining - the estimated number of remaining calls allowed by this API key this minute

You can inspect the response header with the -i option to curl like so:

curl -i 'http://developer.echonest.com/api/v4/artist/profile?api_key=N6E4NIOVYMTHNDM8J&name=weezer'

This returns a response header with content like so:

HTTP/1.1 200 OK
Content-Length: 135
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 62
X-RateLimit-Used: 58

This indicates that the current rate limit is 120 calls per minute. In the current minute 58 calls have been made and we estimate that you will have 62 calls remaining for the current minute.

You can use the information in the response header to automatically adjust your call volume to ensure that your application will remain under its rate limit. If your application needs a guaranteed rate limit contact us at developer@echonest.com.