Backfill transactions across users
Bulk-upload historical transactions spanning multiple users in a single backfill operation.
What this covers
Bulk-uploading historical transactions for many users in one operation — for example, migrating a book of existing users onto Connect Earth in bulk rather than one at a time. This is a different case from backfilling a single user's history after consent, which covers one user's transactions at the moment they opt in. The two are related: the ramp-up guidance below applies to both.
Endpoint and batching
Upload transactions to POST /transaction/bulk/upload in batches of up to 250 transactions per request, the same endpoint used for single-user backfills. Each transaction in a batch carries its own userId and geo, so a single request can carry transactions belonging to multiple different users — you are not restricted to one user per request. This has been confirmed with engineering, and the public API reference is being updated to reflect it.
For the full request and response schema, see the POST /transaction/bulk/upload reference.
Recommended throughput and ramp-up
The sustained maximum is 10 requests per second — at 250 transactions per batch, that's around 2,500 transactions per second at full rate. If your migration needs higher throughput than this, contact Connect Earth to discuss your use case.
Rather than sending at full rate from the first request, ramp up gradually: increase by 1 request per second per minute until you reach your agreed maximum. This gives Connect Earth's processing pipeline time to scale up behind the queue.
Monitor and verify
Once uploaded, transactions are queued and processed asynchronously. Use the same polling pattern described in Backfill transaction history after user consent: poll an aggregate endpoint such as POST /monthly-insights/totals and watch the processing flag in the response — once it is false, the backfill has finished processing for that user. The transaction_count field is only useful for showing percentage-complete progress.