> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: "Run a batch"
description: "Start one run per input item of a function, workflow, tool, or agent in a single request. Returns 202 with a batch ID and every run ID."
method: "POST"
endpoint: "/v1/:type/:name/batch"
order: 9
group: "Gateway: run components"
last_verified: 2026-10-08
---



`POST /v1/:type/:name/batch`

Start one run per input item in a single request.


  ## Parameters

  - `X-API-KEY` _header_ **required** — A service key with the `run` scope.
  - `X-DEPLOYMENT-ID` _header_ — The deployment to use. Leave it out when the key was created for one environment; the live deployment of that environment is used.
  - `type` _string_ **required** — `functions`, `workflows`, `tools`, or `agents`.
  <ApiAttribute name="name" type="string" description="The component's registered name. `agnt5 components --env <environment>` lists them." required={true} />
  - `items` _array_ **required** — The inputs, one JSON object per run.



  ## Request example


```bash
curl -X POST "https://gw.agnt5.com/v1/workflows/order_workflow/batch" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: {service_key}" \
  -d '{"items": [{"order_id": "4512"}, {"order_id": "4513"}]}'
```

```javascript
fetch('https://gw.agnt5.com/v1/workflows/order_workflow/batch', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-KEY': serviceKey },
  body: JSON.stringify({ items: [{ order_id: '4512' }, { order_id: '4513' }] })
})
```


  ```json {{ title: 'Response (202 Accepted)' }}
  {
    "batch_id": "01a11cb0-...",
    "run_ids": ["01a11cb0-...", "01a11cb0-..."],
    "status": "started",
    "total_items": 2
  }
  ```