Job, Bulk API 2.0
A Job in Bulk API 2.0 is the work unit Salesforce uses to insert, update, delete, or query large volumes of records asynchronously. The caller creates a job, uploads a CSV file with up to 150 milli…
Definition
A Job in Bulk API 2.0 is the work unit Salesforce uses to insert, update, delete, or query large volumes of records asynchronously. The caller creates a job, uploads a CSV file with up to 150 million records, optionally adds more data in chunks, then closes the job to signal upload completion. Salesforce processes the data in parallel batches under the covers, with the client polling for status until the job completes. Bulk API 2.0 simplified the original Bulk API 1.0 by removing the batch-management work; the platform now handles batching automatically.
Bulk API 2.0 is the right tool for any record-load operation above roughly 10,000 records. It is also the only practical path for nightly data syncs, multi-million-row migrations, and any process where the REST API''s per-call limits would dominate. The Job object exposes status (Open, UploadComplete, InProgress, JobComplete, Failed, Aborted), the records-processed counters, and links to the result files (successful records, failed records). Job-based integration is mandatory for any Salesforce-connected ETL tool, data migration, or backup product.
The Bulk API 2.0 job lifecycle from create to complete
Job lifecycle states
A Bulk API 2.0 job moves through Open (created, accepting uploads), UploadComplete (caller signaled completion), InProgress (Salesforce processing the data), JobComplete (all batches finished), Failed (a fatal error stopped processing), and Aborted (the caller cancelled). The client polls the job''s status endpoint every few seconds; once JobComplete or Failed, the client downloads the result files.
Bulk API 1.0 vs. 2.0
Bulk API 1.0 (still supported) required the caller to break the data into batches manually. Bulk API 2.0 (the modern path) accepts the data in a single upload and Salesforce handles batching. Bulk 2.0 also supports CSV-only data, simpler error handling, and the new ingest job lifecycle. New integrations should default to 2.0; legacy ones can migrate when convenient.
The Job standard object
Each Bulk API job creates a Job record (queryable via Job, BulkAPI v2). Fields include Operation (Insert, Update, Upsert, Delete, Query), Object, Status, NumberRecordsProcessed, NumberRecordsFailed, CreatedDate, and SystemModstamp. Querying the Job object exposes the full history of bulk operations, useful for audit and ETL job health monitoring.
Ingest job operations
The five ingest operations are Insert, Update, Upsert (insert if no match, update if match), Delete, and HardDelete (permanent delete, requires the Bulk API Hard Delete permission). Upsert uses the External ID field on the target object to match. The platform validates the operation type against the user''s field-level security at job creation; restricted users cannot create jobs that bypass their FLS.
Query jobs
Bulk API 2.0 also supports Query jobs that return large SOQL result sets via a downloadable file. The Query job runs asynchronously, processes the SOQL on the server, and writes the result to a downloadable URL. Use Query jobs when a synchronous SOQL would exceed the 50,000-row Apex limit; the bulk version has no such cap.
Throughput and parallelism
Bulk API 2.0 processes work in parallel under the covers, with multiple batches running concurrently. Throughput depends on the operation type, the object''s complexity (triggers, validation rules, sharing recalculations), and the org''s overall load. Typical throughput is hundreds of records per second for simple inserts; complex inserts on heavy objects can run an order of magnitude slower.
Error handling and partial success
Each row in a Bulk job succeeds or fails independently. The successful-records and failed-records result files let the caller reprocess only the failures. Common failure modes: validation rule fires, required field missing, lookup target doesn''t exist, trigger throws an exception. The error message on each failed row includes the field, the rule, and the diagnostic; well-designed integrations parse these and route them to a remediation queue.
Run a Bulk API 2.0 ingest job
The lifecycle is: create job, upload CSV, mark upload complete, poll status, download results. Five API calls total for a basic job.
- Create the job
POST /services/data/v60.0/jobs/ingest with JSON body specifying Object, Operation, and externalIdFieldName (for upserts). Returns the job ID and the upload URL.
- Upload the CSV
PUT the CSV data to the upload URL. The data can be up to 150 million records or 100 GB; large files are streamed.
- Mark upload complete
PATCH /services/data/v60.0/jobs/ingest/{jobId} with state: UploadComplete. Signals Salesforce to start processing.
- Poll status
GET /services/data/v60.0/jobs/ingest/{jobId} every few seconds. Read the state field. Once state is JobComplete or Failed, proceed.
- Download results
GET /services/data/v60.0/jobs/ingest/{jobId}/successfulResults and .../failedResults. Parse and act on failures.
- Audit the Job record
Query the Job object via SOQL for historical job records; useful for ETL monitoring.
The target sObject for the operation.
Insert, Update, Upsert, Delete, HardDelete, or Query.
The unique alternate key for upsert matching.
The actual records to process.
Lifecycle status; the caller transitions Open to UploadComplete.
- Bulk API 2.0 processes work asynchronously. Code that needs synchronous response should use the REST API instead, not Bulk.
- Job processing time varies. Throughput depends on triggers, validation rules, and overall org load; do not assume linear scaling.
- Failed records are returned in a separate file. Successful upserts and inserts must be reconciled with the input file using row position or an upload-provided correlation field.
- Bulk API 2.0 has its own rate limits separate from the REST API. Heavy ETL workloads need to plan around them.
Trust & references
Cross-checked against the following references.
- Bulk API 2.0 Developer GuideSalesforce Developers
- Bulk API 2.0 JobsSalesforce Developers
Straight from the source - Salesforce's reference material on Job, Bulk API 2.0.
- Bulk API 2.0 Query JobsSalesforce Developers
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Bulk API 2.0 Job?
Q2. What states do Bulk API 2.0 Jobs transition through?
Q3. Why use Bulk API 2.0 over 1.0?
Discussion
Loading discussion…