Work with Batches

A batch is a set of records sent to the server in an HTTP POST request. Each batch is processed independently by the server, not necessarily in the order it’s received.

A batch is created by submitting a CSV, XML, or JSON representation of a set of records and any references to binary attachments in an HTTP POST request. When created, the status of a batch is represented by a BatchInfo resource. When a batch is complete, the result for each record is available in a result set resource.

Batches can be processed in parallel. It’s up to the client to decide how to divide the entire data set into a suitable number of batches.

Adjust batch sizes based on processing times. Start with 5000 records and adjust the batch size based on processing time. If it takes more than 5 minutes to process a batch, it can be beneficial to reduce the batch size. If it takes a few seconds, increase the batch size. If you get a timeout error when processing a batch, split your batch into smaller batches, and try again.

Salesforce provides an additional API, Bulk API 2.0, which uses the REST API framework to provide similar capabilities to Bulk API. Bulk API 2.0 removes the need for creating and monitoring batches, and it lets you load record data for a job directly. For more information on Bulk API 2.0, see the Bulk API 2.0 Developer Guide.

  1. Add a Batch to a Job

    Add a new batch to a job by sending a POST request to this URI. The request body contains a list of records for processing.

  2. Monitor a Batch

    You can monitor a Bulk API batch in Salesforce.

  3. Get Information for a Batch

    Get information about an existing batch by sending a GET request to this URI.

  4. Get Information for All Batches in a Job

    Get information about all batches in a job by sending a GET request to this URI.

  5. Interpret Batch State

    This list gives you more details about the various states, also known as statuses, of a batch. The batch state informs you whether to proceed to get the results, or whether you must wait or fix errors related to your request.

  6. Get a Batch Request

    Get a batch request by sending a GET request to the following URI. This is available in API version 19.0 and later.

  7. Get Batch Results

    Get results of a batch that completed processing by sending a GET request to this URI. If the batch is a CSV file, the response is in CSV format. If the batch is an XML or JSON file, the response is in XML or JSON format, respectively.

  8. Handle Failed Records in Batches

    A batch can have a Completed state even if some or all of the records failed. If a subset of records failed, the successful records aren’t rolled back. Likewise, even if the batch has a Failed state or if a job is aborted, some records could have completed successfully.