Bulk API 2.0

Bulk API 2.0
Bulk Uploading and Upserting
Bulk Queries
Walkthrough for Query Jobs
Create a Query Job
Get Information About a Query Job
Get Results for a Query Job
Abort a Query Job
Delete a Query Job
Get Information About All Query Jobs
PDF

Get Results for a Query Job

Gets the results for a query job. The job must have the state JobComplete.

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

You must 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 Gets a specific set of results.

If this parameter is omitted, the request returns as many rows as can be listed, starting at the beginning of the results. If there are more results than can be listed, the response’s Sforce-Locator header contains the locator value to get the next set of results.

See Example and Rules and Guidelines.

 Optional
maxRecords The maximum number of records to retrieve per set. The request is still subject to the size limits.

If you are working with very large query result sets, 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 by in the maxRecords parameter. This splits the results into smaller sets.

 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 For an Unsuccessful Request
If the request fails, the status code is 204 (No Content).
Response Headers
Header Description
Sforce-NumberOfRecords The number of records in this set.
Sforce-Locator

The locator to get the next set of results (if there are any).

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.

See Example and Rules and Guidelines.

If there are no more results, this value is the string ‘null’.

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

The first request doesn’t use locator because we don’t know what value to use yet.

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

Because there are more results than can be returned in a single response, the value of the Sforce-Locator header is not ‘null’. We use its value, MTAwMDA, as the locator query parameter to get the next set of results: 

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. We use its new value, MjAwMDAw, as the locator query parameter to get the next set of results: 

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 locator is the string ‘null’, indicating that there are no more results to fetch.

1HTTP/1.1 200 OK
2
3Sforce-Locator: null
4Sforce-NumberOfRecords: 6155
5...
6
7"Id","Name"
8...

Rules and Guidelines

To use this URI, 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.