Retrieve Multiple Records with Fewer Round-Trips

Use a GET or POST request with sObject Collections to retrieve one or more records of the same object type. A list of sObjects that represents the individual records of the specified type is returned. The number of sObjects returned matches the number of IDs passed in the request.

You can specify approximately 800 IDs before the URL length causes the HTTP 414 error URI too long. To retrieve more records than the URL length can accommodate, use a POST request to retrieve up to 2,000 records of the same object type. If you use POST, the IDs and fields of the records to retrieve are specified in the request body.

Request Syntax

If you’re using a GET request, use the following syntax, where SObjectName is the object type of the records from which you’re retrieving data.

GET /vXX.X/tooling/composite/sobjects/SObjectName?ids=recordId1,recordId2&fields=fieldname1,fieldname2

If you’re using a POST request, use the following syntax, where SObjectName (required) is the object type of the records from which you’re retrieving data.

1POST /tooling/composite/sobjects/SObjectName
2{
3   "ids" : ["recordId1", "recordId2", "recordId3"],
4   "fields" : ["fieldname1", "fieldname2"]
5}

Parameters

Parameter	Description
ids	Required. A list of one or more IDs of the objects to return. All IDs must belong to the same object type.
fields	Required. A list of fields to include in the response. The field names you specify must be valid, and you must have read-level permissions to each field.

Usage Guidelines

If you specify an invalid field name or a field name that you don’t have permission to read, HTTP 400 Bad Request is returned.
If you don’t have access to an object, or if a passed ID is invalid, the array returns null for that object.

Request Example

If you’re using a GET request, use the syntax shown in the following example.

GET /tooling/composite/sobjects/SObjectName?ids=001xx000003DGb1AAG,001xx000003DGb0AAG,001xx000003DGb9AAG&fields=id

If you’re using a POST request, use a request body as shown in the following example.

1POST /tooling/composite/sobjects/SObjectName
2{
3   "ids" : ["001xx000003DGb1AAG", "001xx000003DGb0AAG", "001xx000003DGb9AAG"],
4   "fields" : ["id"]
5}

Response Body Example

1[
2   {
3      "attributes" : {
4         "type" : "SObjectName",
5         "url" : "/services/data/v45.0/tooling/sobjects/SObjectName/001xx000003DGb1AAG"
6      },
7      "Id" : "001xx000003DGb1AAG"
8   },
9   {
10      "attributes" : {
11         "type" : "SObjectName",
12         "url" : "/services/data/v45.0/tooling/sobjects/SObjectName/001xx000003DGb0AAG"
13      },
14      "Id" : "001xx000003DGb0AAG"
15   }
16]

Tooling API