Bulk API 2.0 and Bulk API Developer Guide
jNote: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.
Get Results for a Query Job
Syntax
URI:
/services/data/vXX.X/jobs/query/queryJobId/results
or
1/services/data/vXX.X/jobs/query/queryJobId/results
2 ?locator=locator
3 &maxRecords=maxRecordsAvailable since release:
This resource is available in API version 47.0 and later.
Formats: CSV
HTTP methods: GET
Authentication: Authorization: Bearer token
Request parameters:
| Parameter | Description | Required or Optional |
|---|---|---|
| queryJobId | The ID of the query job. | Required |
| locator | A string that identifies a specific set of query
results. Providing a value for this parameter returns
only that set of results. Omitting this parameter returns the first set of results. You can find the locator string for the next set of results in the response of each request. See Example and Rules and Guidelines. As long as the associated job exists, the locator string for a set of results does not change. You can use the locator to retrieve a set of results multiple times. |
Optional |
| maxRecords | The maximum number of records to retrieve per set of results for the query. The
request is still subject to the size limits. If you are working with a very large number of query results, you may experience a timeout before receiving all the data from Salesforce. To prevent a timeout, specify the maximum number of records your client is expecting to receive in the maxRecords parameter. This splits the results into smaller sets with this value as the maximum size. If you don’t provide a value for this parameter, the server uses a default value based on the service. |
Optional |
Response Body
If the request is successful, the status code is 200 (OK) and the request body contains the results of the job’s query. For example:
1"Id","Name"
2"005R0000000UyrWIAS","Jane Dunn"
3"005R0000000GiwjIAC","George Wright"
4"005R0000000GiwoIAC","Pat Wilson"
5...Response Headers
| Header | Description |
|---|---|
| Sforce-NumberOfRecords | The number of records in this set. |
| Sforce-Locator | The locator for the next set of results (if there are
any). Use this value in other GET request to retrieve
the next set of query results. This value is a pseudo random string (for example, MTAwMDA). The length of this string varies depending on how many sets of results there are. If there are no more sets of query results, this value is the string ‘null’. See Example and Rules and Guidelines. |
Example
This example retrieves the results for the job with ID 750R0000000zxr8IAA. It also shows how to use the locator and maxRecords query parameters. (In this example, we use them both, but they are independent. You don’t have to use them together.) For an example on how to download data in parallel, see Get Parallel Results for a Query Job.
We start by sending an initial request to retrieve the first set of query results. We don’t use the locator parameter because we want to get the first set of results.
1curl --include --request GET \
2--header "Authorization: Bearer token" \
3--header "Accept: text/csv" \
4https://instance.salesforce.com/services/data/vXX.X/jobs/query/750R0000000zxr8IAA/results
5?maxRecords=50000The response body is:
1HTTP/1.1 200 OK
2...
3Sforce-Locator: MTAwMDA
4Sforce-NumberOfRecords: 50000
5...
6
7"Id","Name"
8"005R0000000UyrWIAS","Jane Dunn"
9"005R0000000GiwjIAC","George Wright"
10"005R0000000GiwoIAC","Pat Wilson"
11...The response includes MTAwMDA as a value for the Sforce-Locator header. This value is not ‘null’, which means that there are more query results that we can retrieve.
To retrieve the next set of query results, we send another request, using the locator parameter and the locator string, MTAwMDA.
1curl --include --request GET \
2--header "Accept: text/csv" \
3https://instance.salesforce.com/services/data/vXX.X/jobs/query/750R0000000zxr8IAA/results
4?locator=MTAwMDA&maxRecords=50000The response body is:
1HTTP/1.1 200 OK
2...
3Sforce-Locator: MjAwMDAw
4Sforce-NumberOfRecords: 50000
5...
6
7"Id","Name"
8"005R0000000UyrWIAv","James Wu"
9"005R0000000GiwjIxx","Samantha Jones"
10"005R0000000GiwoIAB","Doug West"
11...Notice that the locator value has changed. This means that there is another set of query results that we can retrieve. We use the new locator string, MjAwMDAw, in another request.
1curl --include --request GET \
2--header "Accept: text/csv" \
3https://instance.salesforce.com/services/data/vXX.X/jobs/query/750R0000000zxr8IAA/results
4?locator=MjAwMDAw&maxRecords=50000We repeat this process until the value of the Sforce-Locator header is ‘null’, which indicates that there are no more results to retrieve.
1HTTP/1.1 200 OK
2
3Sforce-Locator: null
4Sforce-NumberOfRecords: 6155
5...
6
7"Id","Name"
8...Rules and Guidelines
To retrieve your full set of query results, follow these rules and guidelines.
- Use /services/data/vXX.X/jobs/query/queryJobId/results to get the first set of results for the job.
- If there are no more results, the Sforce-Locator header’s value is the string ‘null’. Otherwise, set the locator query parameter to that value to get the next set of results.
- Repeat this process until the Sforce-Locator header’s value is the string ‘null’. That set is the last set of results.