Gets the results for a query job. The job must have the state JobComplete.
If encoding is enabled for Bulk API 2.0 Query job responses, there is a significant improvement in performance of query result downloads. This not the total query time, but a reduction in the time to download the results.
Tip
URI:
/services/data/vXX.X/jobs/query/queryJobId/results
or
1/services/data/vXX.X/jobs/query/queryJobId/results
2 ?locator=locator
3 &maxRecords=maxRecordsUse the same API version to get query results that you used to create the query. Otherwise, the call returns a 409 error.
Note
Available 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
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...In API version 50.0 and later, the order of the columns returned by the query is the same as the order you requested them. In version 49.0 and earlier, the order of the columns is returned alphabetically.
Note
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,
If there are no more sets of query results, this value is the string ‘null’. See Example and Rules and Guidelines . |
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 Accept header must match what was specified when the job was created. Currently, only text/csv is supported.
Note
The 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...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.
For locator, use only the value from the Sforce-Locator header. Don’t try to guess what it is. How this parameter is evaluated is subject to change.
Note
Repeat this process until the Sforce-Locator header’s value is the string ‘null’. That set is the last set of results.
See Also
j