---
title: "Run an ad-hoc batch"
method: POST
path: "/v2/batch-executions"
tags: ["Batch Executions"]
---

# Run an ad-hoc batch

`POST /v2/batch-executions`

## Request

- Base URL: `https://app.aiva.works` (the document declares no server; this is the origin it was published from)
- URL: `https://app.aiva.works/v2/batch-executions`
- Auth: API key in header `X-API-KEY`

Runs a one-time batch of the tests selected by labels and returns the ID of the started batch execution.

## Request body

- RunBatchExecutionV2Request
  - `name` string, nullable: Name of the batch execution.
  - `labels` string[], required: Tests carrying all of these labels run. At least one label is required.
  - `maxNumberOfAgents` integer, nullable: Maximum number of agents running tests in parallel. Omit to run the tests sequentially.
  - `globalVariableOverrides` object, nullable: Variable overrides applied to every test. Values must not be empty.
  - `variableOverridesPerTest` object, nullable: Variable overrides per test, keyed by test ID. They win over the global overrides.
  - `gatewayId` string, guid, nullable: ID of the gateway to run on. Omit to use each test's default gateway (the public internet if it has none).

## Response `202`

Batch execution started

- RunBatchExecutionV2Response
  - `executionId` string, guid: ID of the started batch execution.

## Other responses

- `400`: The request is not valid
- `401`: Unauthorized
- `403`: User does not have permission to access batches
- `429`: Queue limit exceeded -- retry later
- `500`: Server Error

---

[API](https://skmtc.dev/aiva/apis/aiva-cloud-api.md) · [All operations](https://skmtc.dev/aiva/apis/aiva-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aiva/apis/aiva-cloud-api/revisions/70eef14d3bcd?raw)