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=maxRecords

Use 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 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=50000

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=50000

The 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=50000

We 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.

1. Use /services/data/vXX.X/jobs/query/queryJobId/results to get the first set of results for the job.
2. 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

3. Repeat this process until the Sforce-Locator header’s value is the string ‘null’. That set is the last set of results.