Bulk processing

The _bulk endpoint allows for efficient processing of multiple requests in a single operation. It supports streaming, parallel or sequential processing, and atomic execution.

Streaming support

Bulk requests can be streamed without requiring the entire request to be loaded into memory.

To enable script streaming, include the following content type headers in your HTTP request: application/vnd.formance.ledger.api.v2.bulk+script-stream

Parallel v. Sequential Processing

Bulk elements can be processed either in parallel or sequentially, controlled by the parallel query parameter:

• parallel=true: Elements are processed in parallel, improving throughput.
• parallel=false: Elements are processed sequentially, maintaining order.

Atomic Bulk Execution

Bulk elements can be committed atomically or independently using the atomic query parameter:

• atomic=true: The entire batch is committed as a single transaction. If any element fails, the entire batch is rolled back.
• atomic=false: Each element is processed independently. If one element fails, it does not affect the others.

note

Since requests can be processed either in parallel or atomically, you cannot set parallel=true and atomic=true at the same time.

Usage Example

To send a bulk request with parallel processing enabled and atomic execution disabled, use the following curl command:

curl -H "Authorization: Bearer $(fctl cloud generate-personal-token)" \
     -X POST <stack-url>/api/ledger/v2/<ledger-name>/_bulk?parallel=true&atomic=false \
     -H 'Content-Type: application/vnd.formance.ledger.api.v2.bulk+script-stream' \
     --data-binary @<stream file location>