Salesforce Bulk API 2.0 vs Bulk API 1.0: The Ultimate Developer & Architect Guide

When moving millions of records into or out of Salesforce, choosing the wrong API architecture can cause severe execution bottlenecks, governor limit breaches, complex client-side retry logic, and hours of integration downtime. For over a decade, Bulk API 1.0 was the workhorse for high-volume data operations. However, Bulk API 2.0 fundamentally reimagined how Salesforce processes massive datasets server-side.

Whether you are migrating millions of Accounts, syncing enterprise ERP tables nightly, or pulling massive reporting datasets into a data warehouse like Snowflake or Redshift, understanding the operational mechanics of Bulk API 2.0 vs Bulk API 1.0 is vital for Salesforce solution architects and data engineers.

1Query Workflow Comparison: How Bulk Data Retrieval Evolved

Retrieving large record volumes (1M+ rows) via SOQL queries highlights the architectural gulf between Bulk API 1.0 and Bulk API 2.0. Let’s analyze how the execution flow works under both frameworks.

Bulk API 1.0 Query Workflow: Client-Managed Batching

In Bulk API 1.0, executing a query required the client application to manage job states, batch assignments, and result polling across multiple generated batch IDs.

Figure 1: Legacy Bulk API 1.0 Multi-Step Query & Batch Processing Loop

As illustrated in Figure 1, executing a query in Bulk API 1.0 followed a 5-step iteration cycle:

1. Create Query Job: Post a job request defining target object, content type (CSV/XML), and operation (`query`).
2. Create Batches with Query: Post the SOQL string (`SELECT Id, Name FROM Account`) into batch slots. For massive datasets, developers had to manually configure PK Chunking headers to force Salesforce to split records across generated batches.
3. Asynchronous Batch Processing: Salesforce queues and processes each batch independently.
4. Retrieve Batch Result Sets: Client polls each batch status, receives an array of result IDs, and requests individual result payloads batch-by-batch.
5. Client-Side Iteration & Aggregation: Client loops through all batch files, handles failures per batch, and stitches files together.

Bulk API 2.0 Query Workflow: Streamlined Single-Response Stream

Bulk API 2.0 eliminates manual batch creation and client-side chunk management altogether.

Figure 2: Modern Bulk API 2.0 Streamlined Query Architecture

As shown in Figure 2, Bulk API 2.0 shrinks the data extraction lifecycle down to 3 frictionless steps:

1. Create Query Job: Submit a single POST request containing the SOQL query string (`operation: query; SELECT Id, Name FROM Account`).
2. Automated Server-Side Processing: Salesforce automatically calculates query execution plans, applies internal chunking algorithms, and executes tasks across multithreaded cloud workers.
3. Retrieve Unified Result Set: Receive a clean, paginated HTTP stream. If the result exceeds 1 GB, Salesforce provides a `locator` header parameter to effortlessly fetch the next page of records in sequence.

2Ingestion Mechanics: Data Loading & Chunking

Data loading (inserting, updating, upserting, or deleting records) underwent a similar transformation.

3Governor Limits & Daily Allocations

One of the most compelling reasons to adopt Bulk API 2.0 is how Salesforce counts data usage against org governor limits.

4REST API Endpoint & OAuth Alignment

Bulk API 1.0 used a legacy asynchronous endpoint path (`/services/async/XX.0/`). In contrast, Bulk API 2.0 fully integrates with standard Salesforce REST API conventions under `/services/data/vXX.0/`.

Bulk API 2.0 Ingestion Endpoints Code Pattern

// 1. Create Ingestion Job
POST /services/data/v60.0/jobs/ingest
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "object": "Account",
  "contentType": "CSV",
  "operation": "insert",
  "lineEnding": "LF"
}

// 2. Upload CSV Data Stream
PUT /services/data/v60.0/jobs/ingest/{jobId}/batches
Authorization: Bearer <access_token>
Content-Type: text/csv

Name,Phone,BillingCity
"Acme Corp","555-0199","San Francisco"
"Apex Systems","555-0200","New York"

// 3. Mark Job Upload Complete
PATCH /services/data/v60.0/jobs/ingest/{jobId}
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "state": "UploadComplete"
}

5Error Handling & Result Retrieval

In Bulk API 1.0, retrieving success and error logs required parsing batch status arrays and fetching individual result XML/CSV files per batch ID.

Bulk API 2.0 simplifies result management with three dedicated REST endpoints per job:

• GET /services/data/v60.0/jobs/ingest/{jobId}/successfulResults

  Returns CSV of successfully inserted/updated records appended with sf__Id and sf__Created columns.

• GET /services/data/v60.0/jobs/ingest/{jobId}/failedResults

  Returns CSV of failed records with exact error messages in sf__Error column.

• GET /services/data/v60.0/jobs/ingest/{jobId}/unprocessedrecords

  Returns records that were not processed before job cancellation or abort.

6Side-by-Side Comparison Matrix

7Architectural Recommendations & Migration Checklist

Transitioning existing ETL scripts, Middleware connectors (MuleSoft, Boomi, Informatica), or custom Python/Node.js integrations to Bulk API 2.0 yields immediate operational benefits:

• Delete Client-Side Batch Slicing Logic: Remove custom loops that break raw CSVs into 10,000-line chunks. Simply stream your raw CSV payload to Bulk API 2.0.
• Standardize OAuth 2.0 Bearer Tokens: Replace legacy session ID header patterns with standard REST OAuth headers (Authorization: Bearer <access_token>).
• Leverage locator Parameter for Queries: When pulling multi-gigabyte queries, inspect the HTTP response header for Sforce-Locator to seamlessly fetch subsequent pages.
• Monitor Job Status via Webhooks or Polling: Poll GET /services/data/v60.0/jobs/ingest/{jobId} until state transitions to JobComplete or Failed.