Tracking the results of bulk job trigger requests.
A BatchOperation tracks the outcome of a bulk trigger request against a Job. When you trigger a job with multiple items in a single request (via POST /v1/jobs/{jobID}/trigger-bulk), Strait creates a batch operation to record how many items were submitted and how many Runs were actually created.
BatchOperation Model
The BatchOperation struct (defined in apps/strait/internal/domain/types.go) contains the following fields:
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the batch operation. |
project_id | string | The project this batch operation belongs to. |
job_id | string | The job that was bulk-triggered. |
item_count | int | Number of items submitted in the bulk trigger request. |
created_count | int | Number of runs actually created (may be less than item_count). |
created_by | string | Actor ID who initiated the bulk trigger (user ID or apikey:<id>). |
created_at | time.Time | Timestamp when the batch operation was created. |
finished_at | *time.Time | Timestamp when all items in the batch have been processed. Null while processing is in progress. |
How Batch Operations Work
Batch operations are not created directly through the API. They are created automatically when a bulk trigger request is made:
- A client sends a
POST /v1/jobs/{jobID}/trigger-bulkrequest containing multiple items. - Strait creates a
BatchOperationrecord withitem_countset to the number of items in the request. - For each item, Strait attempts to create a run. The resulting runs have their
batch_idfield set to the batch operation'sid. created_countreflects the number of runs that were actually created. This may be lower thanitem_countif some items were deduplicated (see dedup_window_secs).- Once all items have been processed,
finished_atis set.
The difference between item_count and created_count is a useful signal. A large gap typically indicates deduplication is filtering out duplicate payloads within the configured window.
Querying Batch Status
Two read-only endpoints are available for inspecting batch operations:
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/batch-operations?project_id=... | List batch operations for a project (paginated with cursor). |
GET | /v1/batch-operations/{batchID}?project_id=... | Get a specific batch operation by ID. |
To find all runs that belong to a specific batch, query runs and filter by batch_id:
GET /v1/jobs/{jobID}/runs?project_id=...&batch_id={batchID}A batch operation is considered complete when finished_at is non-null.
Related Concepts
- Jobs: The job definition that was bulk-triggered.
- Runs: Individual execution instances created by the batch. Each run's
batch_idlinks back to its originating batch operation.