Query Objects in Marketing Cloud Next Using Bulk API 2.0

For complex queries, or queries that you expect to produce a large set of results, use Bulk API 2.0. Bulk API 2.0 executes queries asynchronously.

Prerequisite

Before you issue a query request, create a SOQL statement that specifies the data that you want to retrieve. Remove any line breaks from your SOQL statement. For more information, see Understand SOQL Queries.

Bulk queries don’t support the complete set of SOQL clauses and functions. For more information, see Create a Query Job in the Bulk API 2.0 and Bulk API Developer Guide.

Note

Step 1: Create a Bulk Query Job

To create a bulk query job, issue a POST request to the /services/data/{apiVersion}/jobs/query endpoint. For more information about the properties of the request body, see Create a Query Job in the Bulk API 2.0 and Bulk API Developer Guide.

1POST /services/data/{apiVersion}/jobs/query HTTP/1.1
2Host: YOUR_SUBDOMAIN.my.salesforce.com
3Content-Type: application/json
4Authorization: Bearer YOUR_BEARER_TOKEN
5
6{
7  "operation" : "query",
8  "query" : "SELECT Id, FirstName, LastName, MailingCountry FROM Contact WHERE MailingCountry = 'US'",
9  "contentType" : "CSV",
10  "columnDelimiter" : "COMMA",
11  "lineEnding" : "LF"
12}

If the request is successful, the response includes the job ID (id), which you use to check the status of the request and to retrieve the resulting data.

1{
2  "id": "7501Q00001CfAxxQAF",
3  "operation": "query",
4  "object": "Contact",
5  "createdById": "0051Q00000booXXQAI",
6  "createdDate": "2024-01-18T22:19:31.000+0000",
7  "systemModstamp": "2024-01-18T22:19:31.000+0000",
8  "state": "UploadComplete",
9  "concurrencyMode": "Parallel",
10  "contentType": "CSV",
11  "apiVersion": 60.0,
12  "lineEnding": "LF",
13  "columnDelimiter": "COMMA"
14}

Step 2: Check the Status of the Query

To check the status of a bulk query, issue a GET request to the /data/{apiVersion}/jobs/query/JOB_ID endpoint, replacing JOB_ID with the unique ID of the query job.

1{
2  "id": "7501Q00001CfAdyQAF",
3  "operation": "query",
4  "object": "Contact",
5  "createdById": "0051Q00000bogY5QAI",
6  "createdDate": "2024-01-18T22:25:23.000+0000",
7  "systemModstamp": "2024-01-18T22:25:24.000+0000",
8  "state": "JobComplete",
9  "concurrencyMode": "Parallel",
10  "contentType": "CSV",
11  "apiVersion": 60.0,
12  "jobType": "V2Query",
13  "lineEnding": "LF",
14  "columnDelimiter": "COMMA",
15  "numberRecordsProcessed": 2,
16  "retries": 0,
17  "totalProcessingTime": 341,
18  "isPkChunkingSupported": false
19}

When the status of the query job is JobComplete, the query has finished running and your data is ready to retrieve.

Step 3: Retrieve the Results

To retrieve the query results, issue a GET request to the /data/{apiVersion}/jobs/query/JOB_ID/results endpoint.

If the request is successful, the response includes the resulting data in the requested format, as shown in this example.

1"Id","FirstName","LastName","MailingCountry"
2"0031Q00002joOXXQAM","Rachel","Rodriquez","US"
3"0031Q00002joOXXQAU","Linda","Rosenberg","US"