Maximum number of rows returned by SOQL queries over the REST API

Row Limit Considerations

• The maximum result size per REST API SOQL query is 2,000 rows.
• This limit can be smaller if you have selected several fields or included blob fields (Long Text Area, Rich Text Area) in your query.
• Responses can be sent with transfer-encoding: chunked, which has no fixed or estimated response size. The underlying reason for limiting the number of records is database performance, not application server performance.

URI and Header Size Limits

• In each REST API call, the maximum combined length of the URI and headers is 16,384 bytes.
• A request exceeding this limit returns a 431 Request Header Fields Too Large error.
• If the URI itself exceeds the limit, the request returns a 414 URI Too Long error.
• The maximum query length is typically smaller than the URI limit because SOQL queries are translated and augmented with additional server-side information (such as user name, org, and complex formula relationships).
• It is recommended to limit the URI length to 2,000 characters and headers to approximately 8,000 bytes.
• To avoid the 431 error, incorporate the SOQL statement into the body of a Composite API request as one of the 25 allowed subrequests.

Handling Pagination with nextRecordsUrl

When a query returns more records than the page size limit, the response includes a nextRecordsUrl field. Use this URL to retrieve subsequent pages of results. Pagination can be performed by calling the /query endpoint surfaced in nextRecordsUrl directly, or by submitting it via the Composite API.