Platform Usage Limits
FINRA reserves the right to limit the number of requests made by an API Client, the number of records returned in a response or the size of a response payload, as well as other parameters as necessary to ensure the reliability, performance, and integrity of the API platform.
Record and Payload Response Size Limits
The API platform enforces two limits regarding the maximum amount of data returned by an API request:
- Maximum Record Limit: the maximum number of records returned by an API request. The maximum records returned is 5000 (default is 1000 if limit parameter is not provided).
- Maximum Payload Size: the maximum payload size returned in the response payload. The maximum payload size returned is 3MB.
Whichever limit is reached first will govern the amount of data returned. For example, if the payload size reaches 3MB for a total of 500 records, only 500 records will be returned (regardless of the limit value). Likewise, if a request results in 10000 records with a payload size is 1MB, only 5000 records will be returned.
There are a number of request parameters and response headers that can be used to work with the record and payload size limits, including:
- Limit parameter: Number of records to return. The max value is 5000. The default value (if limit parameter is not provided on a request) is 1000.
- Offset parameter: Record number to start with (exclusive). If offset is 0 and limit is 20, then records 1 to 20 are returned for a total of 20 records. If offset is 10 and limit is 10, then records 11 to 20 are returned.
- Record-Total response header: Total records found at the time of the request. Use this value when paging through large datasets to determine when all data has been retrieved.
- Record-Offset response header: Set to match the offset value provided with the request.
- Record-Limit response header: Set to match the limit value provided with the request or the platform maximum limit, whichever is smaller.
- Record-Max-Limit response header: Returns the current maximum number of records that will be returned by the API platform. Use to build a flexible integration that can adapt to future record limit changes.
- Response-Payload_Max_Size response header: Returns the current maximum payload size (in MB) returned by the API platform. Use to build a flexible integration that can adapt to future payload response size changes.
- API clients should properly use all of the request parameters and request/response headers in order to page through large datasets.
- Use the limit parameter to reduce the number of records returned. Do not use the limit parameter to try and retrieve a large dataset by increasing this value. To retrieve a large dataset use the limit and offset parameters together to page through a dataset to prevent issues when the number of records available exceeds the maximum limit.
- To maximize the number of records returned in a response minimize the number of fields you return and use the text/plain Accept header on your requests whenever possible (e.g. the Market Transparency datasets support text/plain).
- API clients should count the number of records returned in each response in order to ensure all expected data is returned, and to adapt future requests if less data than expected was returned because the record and/or the response payload size limits are reached.