> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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…

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`

<ParamField body="items" type="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.
</ParamField>

### Response

`BatchTriggerResponse`

<ResponseField name="accepted" type="integer" required>
  Count of successfully queued jobs.
</ResponseField>

<ResponseField name="rejected" type="integer" required>
  Count of rejected items.
</ResponseField>

<ResponseField name="results" type="BatchTriggerItemResult[]" required>
  One entry per input item, in original order.

  <Expandable title="BatchTriggerItemResult">
    <ResponseField name="index" type="integer" required>
      0-based index in the input items array.
    </ResponseField>

    <ResponseField name="job_id" type="string,null">
      UUID of the queued job, if accepted.
    </ResponseField>

    <ResponseField name="status" type="string,null">
      Job status, if accepted ('queued').
    </ResponseField>

    <ResponseField name="error" type="string,null">
      Reason this item was rejected, if any.
    </ResponseField>
  </Expandable>
</ResponseField>

### Status codes

| Code  | Meaning             |
| ----- | ------------------- |
| `200` | Successful Response |
| `422` | Validation Error    |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.computer.stateset.app/api/v1/trigger/batch' \
    --header 'X-API-Key: YOUR_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"
      }
    ]
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "accepted": 1,
    "rejected": 1,
    "results": [
      {
        "index": 1,
        "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "status": "pending",
        "error": "string"
      }
    ]
  }
  ```
</ResponseExample>