Terms :: Rate Limiting

The basic 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 200 photos per hour, 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 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.

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 limit proves insufficient. Under such circumstances, we may offer extended FREE limits for applications that use and contribute to our face index. This excludes any service that only use private namespaces or are not freely available to end-users (see requirements below). For extended private namespacing, rate limits, SLA we offer Premium Licensing.

Each whitelisted account is allowed more requests per hour, depending on the service requirements and level of contribution of new face tags to our index. If you are developing an application that should be considered 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. Your service or application must also:

  • Contribute to our index: We currently offer facebook, twitter, and private-namespace indexing. While we enforce privacy and access restrictions on all namespaces, the facebook and twitter index information is shared with other applications using the face.com API. We measure index contribution by amount training-set data provided through calls to tags.save method. Such calls are expected to provide training-set data for new users, or extend the training-set of existing users. Use of duplicate or bad data is against our terms, and will get you blacklisted.
  • Follow our API Terms. Primarily, your app:
    • does not offend or violate user privacy in any way
    • informs users they were tagged, and provides them with the ability to remove or correct tags
    • includes proper attribution
    • is freely accessible to end users

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 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 response 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).

Premium Licensing

If you're interested in extending your free license limits, and your service does not qualify for our whitelisting option, we offer volume based licensing options. Please contact us, letting us know what your requirements are, and we'll get back to you asap.

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. You know that you are blacklisted if your client is unable to get a response for a 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 if all is good we'll get your account working again.