Trigger Agent Batch

Submit up to 50 jobs in a single API call. Per-item validation: bad rows surface as individual errors in the response without blocking the rest…

POST /api/v1/trigger/batch

cURL

curl --request POST \
  --url 'https://api.computer.stateset.app/api/v1/trigger/batch' \
  --header "X-API-Key: $STATESET_COMPUTER_USE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "agent_type": "general",
      "effort": "low",
      "instruction": "Open https://example.com and report the page title.",
      "max_cost_usd": 0.1,
      "model": "haiku",
      "webhook_url": "https://hooks.example.com/cua"
    }
  ]
}'

200

{
  "accepted": 1,
  "rejected": 1,
  "results": [
    {
      "index": 1,
      "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "pending",
      "error": "string"
    }
  ]
}

Submit up to 50 jobs in a single API call.

Per-item validation: bad rows surface as individual errors in the response without blocking the rest. The whole batch consumes ONE rate-limit slot and ONE quota check (sized to the count of well-formed items), so this is the right path for tenants enqueuing many small tasks at once.

Idempotency. Pass an Idempotency-Key header to make a batch replay-safe: a retried call returns the original batch’s job ids and sets the Idempotency-Replayed: true header. Each item gets a derived idempotency key of the form v1.trigger.batch:<your-key>:<index>, so partial replays are well-defined too.

Request body

BatchTriggerRequest

items · TriggerRequest[] · required

List of jobs to enqueue (1..50). Each item is validated independently — bad items are rejected per-row, valid items are still accepted and queued.

Response

BatchTriggerResponse

accepted · integer · required

Count of successfully queued jobs.

rejected · integer · required

Count of rejected items.

results · BatchTriggerItemResult[] · required

One entry per input item, in original order.

Show BatchTriggerItemResult

index · integer · required

0-based index in the input items array.

job_id · string,null

UUID of the queued job, if accepted.

status · string,null

Job status, if accepted (‘queued’).

error · string,null

Reason this item was rejected, if any.

Status codes

Code	Meaning
200	Successful Response
422	Validation Error

cURL

curl --request POST \
  --url 'https://api.computer.stateset.app/api/v1/trigger/batch' \
  --header "X-API-Key: $STATESET_COMPUTER_USE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "agent_type": "general",
      "effort": "low",
      "instruction": "Open https://example.com and report the page title.",
      "max_cost_usd": 0.1,
      "model": "haiku",
      "webhook_url": "https://hooks.example.com/cua"
    }
  ]
}'

200

{
  "accepted": 1,
  "rejected": 1,
  "results": [
    {
      "index": 1,
      "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "pending",
      "error": "string"
    }
  ]
}