Attention: This site does not support the current version of your web browser. To get the best possible experience using our website we recommend that you upgrade to a newer version or install another browser


Requests to the FamilySearch API may be rate-limited on a per-user basis. This means that even if a user has two different active sessions with two different products, their requests are all still throttled together.

Throttling policies are established in terms of the amount of processing time per real time. For example, requests could be given 3 minutes of execution time within a 1 minute window. Different endpoints have different throttling windows.

Warning Throttling is implemented on a per-user basis. If a user is not signed-in, the app key is used. An app that does not use threads may still receive a throttled response if a user has a session open with another product that uses the FamilySearch API.

When the throttling limit is reached, the server responds with an HTTP status code of 429 Service Unavailable and a Retry-After header that advises how many seconds to wait to make another request.

Server: Apache-Coyote/1.1
Retry-After: 5
Content-Type: application/x-fs-v1+xml
Transfer-Encoding: chunked
Date: Thur, 01 May 2014 18:55:13 GMT
Connection: close

All responses from FamilySearch servers include the X-PROCESSING-TIME header to help you track the execution time elapsed in milliseconds. This header can be used by developers to apply a correct rate-limiting policy to their application. Information regarding window size, processing time used and processing time remaining will also be returned in a header.

Response Headers Description
X-THROTTLE-WINDOW-SIZE The amount of execution time that is allowed within the window.
X-THROTTLE-MILLIS-USED The amount of execution time, in milliseconds, that has been used in the window.
X-THROTTLE-MILLIS-LEFT The amount of execution time, in milliseconds, that is remaining in the window.

Testing Throttling

If you want to know how your application will respond to throttling events, you can test throttling. In order to do this, you can force the processing time counter to be larger than the throttling limit for the current user. Subsequent requests will determine that the current user has reached the throttling limit and the user will be throttled until the end of the current throttling window.

To do this, make a request to the Throttling Test resource, specifying the amount of time to be spent for the request. The processingTime parameter is the amount of time in milliseconds that you want to add to the sum of the processing time for the current user. For example, if you want to add 60 seconds to the processing sum, specify this amount using the processingTime parameter (60 seconds/minute x 1000 milliseconds/second + 1 = 60001). Future requests from that user will be throttled until the throttling window expires.

Example Request

GET /platform/throttled?processingTime=60001

Authorization: Bearer YOUR_ACCESS_TOKEN_HERE

Some resources aren't throttled so be sure to use a throttled resource when testing.


Select a language