Terms :: Rate Limiting

FREE API

The face.com API services are offered for free. In order to balance server loads, we allow clients to make a limited number of calls to face detection and recognition methods in a given hour.

API Rate Limiting

The default rate limit for calls to the REST API is 5,000 photos per hour (120,000 per day), whether sent through batch or single-photo API calls. The REST API does account-based rate limiting (per API Key). As part of our platform roadmap, we intend to continue and raise rate limits as our platform grows, stay tuned for updates.

Rate limiting currently applies only to these methods (see each call for more details on specific rate limiting):

API methods that submit data to face.com, such as tags.save and faces.train do not affect rate limits. Additionally, requests to tag data and status methods are not charged to a limit. These unlimited methods are still subject to daily limits to promote healthy use and discourage spam.

Note: We also provide an aggressive detection mode, that may find a few more faces (and works a bit slower). This detector uses more resources, thus will be charged as 2 normal requests.

Repeat calls

We apply API session caching so that repeat calls to detection and recognition with the same parameters *should* not be counted repeatedly against the limit. The session cache is set to expire daily, but may expire sooner due to loads on our servers.

Private Namespace limits

You can add up to 1,000 users to the private namespaces in your account. For extended private namespacing see Whitelisting below.

Knowing your limits

Your application can know it's being rate-limited by the REST API if it begins to receive a 'failure' status in the response, with error_code: 202 - API_KEY_USAGE_PASSED_QUOTA. We suggest you monitor current rate limit status, and dynamically throttle requests if necessary. The REST API offers two ways to observe this status:

  1. The account.limits method. Calling this method does not count against the requestor's API limit.
  2. 'usage' section in the response of all API calls.

In both cases the following information is returned:

  • used - how much of the limit has been used in the last time window
  • remaining -  the current limit in effect
  • limit - remaining the number of hits remaining before you are rate limited
  • reset_time - the time the current rate limiting period ends in epoch time.

Whitelisting

Some applications find that the default limits prove insufficient and may apply to be whitelisted to receive extended free limits. To apply for whitelisting, please send us a request on the contact form. We manually review each request, and you can expect an answer within a week. Approval or rejection for whitelisting requests is emailed to the email address associated with the account that filed the application.

Whitelisting Requirements

We do not give preemptive whitelisting for the face.com API. You must have a working application or demo that has a proven need (users or other) for more capacity before we will review whitelisting requests. Your service or application must follow our API Terms:

  • Your application does not offend or violate user privacy in any way
  • It informs users they were tagged, and provides them with the ability to remove or correct tags
  • And it includes proper attribution to face.com

If you have received verification from face.com that your account has been whitelisted, you can verify your whitelisting with the faces.rate_limits method. Calling this method with your credentials will return the rate limit status of the authenticating developer account.

Avoiding the Rate Limiter

The same general techniques and design decisions can be used to avoid the crunch of the rate limiter.

  1. Caching: Store API responses in your application or on your site if you expect high-volume repetitive usage. For example, don't try to call the face.com API on every page load of your hugely popular website. Instead, call our API infrequently, cache the responses on your end, and display the local version on page loads.
  2. Offloading: Queue up detection or recognition requests that are not needed for immediate interaction (for instance, while a user is uploading photos VS. when photos are first displayed).

Blacklisting

We ask that you honor the rate limits and our terms. Consistent failure to avoid the rate-limiter may result in automatically blacklisting your application. If you are blacklisted your client will be unable to get a response for any request sent to the API.

If your application has been blacklisted, please contact us here and specify why you think you were blacklisted and how you intend to fix the cause. We will review your information and get your account working again, if the causing issues have been sorted out.