---
title: "Start several runs"
method: POST
path: "/runs:batchCreate"
tags: ["runs"]
---

# Start several runs

`POST /runs:batchCreate`

## Request

- Base URL: `/api/v1` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/v1/runs:batchCreate`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/axilio-api/docs/runs:batchCreate/post.ts> (a function with typed inputs; its response is checked against the schema)

Starts up to 1000 runs, each as POST /runs would. All are created or none is; an error names the request it is for. A batch may not name the same dedicated phone twice. The batch is refused with 409 while your organization is at its concurrency limit; its runs beyond the limit wait in the queue for a free slot.

## Request body

- AgentRunBatchCreateRequest: Start up to 1000 runs at once. All are created or none is.
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `requests` AgentRunCreateRequest[], nullable, required: The runs to start.
    - `$schema` string, uri: A URL to the JSON Schema for this object.
    - `agent_id` string, uuid: The agent to run, with its current revision and settings.
    - `keep_alive_seconds` integer: How long an agent-mode run holds its phone after a turn ends, so a message in that time continues it on the same phone (default 120 on POST /runs, 0 in a batch). 0 releases the phone at once.
    - `max_cost_microdollars` integer: Most an ad hoc run's model steps may cost, in microdollars (default 10000000).
    - `max_steps` integer: Most model steps an ad hoc run may take (default 500).
    - `model` string: An ad hoc run's model, one of GET /models (default the platform default). A saved agent's run uses the agent's.
    - `network` 'restricted' | 'internet': The sandbox's network for an instructions run: restricted (default) reaches the phone only; internet adds the public internet. Code runs always have internet.
    - `output_schema` object: The JSON Schema an ad hoc run's result must satisfy. A saved agent's run uses the agent's.
    - `pause_timeout_seconds` integer: Longest an ad hoc run waits paused for an answer, in seconds (default 600).
    - `recording_enabled` boolean: Record the screen of an ad hoc run (default false). A saved agent's run uses the agent's.
    - `start_at` string, date-time: Start the run at this time, from a minute to 30 days ahead. Leave out to start now.
    - `start_timeout_seconds` integer: How long the run may wait for a phone before it is cancelled (default 300).
    - `targets` RunTarget[], nullable: The device the run drives (at most one). Leave out for a shared phone.
      - `capabilities` RunTargetCapabilities: What a run needs of its device.
        - `accessibility` boolean: Run in accessibility mode, which needs a phone that supports it and your organization's access to accessibility mode.
      - `device_class` 'phone', required: The kind of device.
      - `ownership` 'dedicated' | 'shared': dedicated: one of your organization's phones, the one phone_id names or any free one. shared: a phone from the shared fleet. Defaults to dedicated when phone_id is set, else shared.
      - `phone_id` string: A dedicated phone of your organization to run on. Leave out for any of yours (ownership dedicated) or a shared phone.
      - `platform` 'android': The device's platform (default android).
    - `task` string: An ad hoc task for an agent to work through a model, with nothing saved.
    - `telemetry_enabled` boolean: Emit telemetry for an ad hoc run (default true). A saved agent's run uses the agent's.
    - `timeout_seconds` integer: Longest an ad hoc run may take, in seconds (default 3600).
    - `variables` object: The run's inputs, bound as variables in the kernel.

## Response `201`

Created

- AgentRunBatchCreateResponse: The runs a batch started, in request order.
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `runs` RunResponse[], nullable, required: The runs, in request order.
    - `$schema` string, uri: A URL to the JSON Schema for this object.
    - `agent_id` string, uuid: The agent the run is of; absent on an ad hoc run.
    - `agent_name` string: The agent's name, on the run lists; absent on an ad hoc run.
    - `cancelled_at` string, date-time: Timestamp when the run was cancelled.
    - `completed_at` string, date-time: Timestamp when the run finished.
    - `created_at` string, date-time, required: Timestamp when the run record was created.
    - `error` string: Why the run failed.
    - `id` string, uuid, required: Run identifier.
    - `input_request` RunInputRequest: What a paused run asks a person: answer it by id to resume the run.
      - `created_at` string, date-time, required: When the run paused.
      - `expires_at` string, date-time, required: When the run stops waiting and fails with input_timeout: the earliest of its pause timeout, its time limit and the end of its session.
      - `id` string, uuid, required: The input request's id, which a resume names.
      - `message` string: The question, for the person answering.
      - `reason` 'one_time_code_required' | 'approval_required' | 'choice_required' | 'challenge_blocked' | 'step_check_failed' | 'caller_requested', required: Why the run paused.
      - `requested_by` 'agent' | 'code' | 'caller', required: agent: the agent asked. code: the script asked, or failed with on_failure ask. caller: the run was paused through the API.
      - `response_schema` object: The JSON Schema the answer must satisfy. Absent takes any answer.
    - `keep_alive_expires_at` string, date-time: Until when an ended agent-mode run holds its phone: :sendMessage before then continues the run there; after it, start a new run.
    - `max_cost_microdollars` integer: Most the run's model steps may cost, in microdollars.
    - `max_steps` integer: Most model steps the run may take.
    - `mode` 'agent' | 'code', required: agent: an agent works the task through a model. code: the agent's script runs.
    - `model` string: The model the run's steps call, one of GET /models.
    - `network` 'restricted' | 'internet': The sandbox's network: restricted reaches the phone only; internet adds the public internet.
    - `output` unknown
    - `output_schema` unknown
    - `pause_timeout_seconds` integer: Longest the run waits paused for an answer, in seconds.
    - `phone_id` string: Phone executing the run.
    - `recording_enabled` boolean: An ad hoc run's own recording choice; absent takes the default (off), and a saved agent's run takes the agent's.
    - `repair` RunRepair: A code run's repair: the agent took over after the script failed and finished the task from the live screen.
      - `proposed_revision_id` string, uuid: The fixed revision the repair proposed, waiting to be promoted. Absent when a fix for the revision was already waiting.
      - `repaired` boolean, required: The script failed and the agent took over.
    - `result_text` string: A short account of the run's result.
    - `revision_id` string, uuid: The agent's revision the run was pinned to when it was made.
    - `run_metadata` object: Arbitrary metadata attached to the run.
    - `schedule_id` string, uuid: The schedule that started the run, if one did.
    - `session_id` string, uuid: Session associated with this run.
    - `start_at` string, date-time: When the run was booked to start; absent for a run started on request.
    - `start_timeout_seconds` integer: How long the queued run may wait for a phone before auto-cancel.
    - `started_at` string, date-time: Timestamp when the run began executing.
    - `status` 'scheduled' | 'queued' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled', required: Current lifecycle state of the run. paused: the run waits on a person; see input_request.
    - `stream_url` string: The run's live event stream (Server-Sent Events), with a short-lived read-only token. Server clients can send the API key header instead.
    - `success` boolean: Whether the run completed without error.
    - `targets` RunTarget[], nullable: The device the run drives.
      - `capabilities` RunTargetCapabilities: What a run needs of its device.
        - `accessibility` boolean: Run in accessibility mode, which needs a phone that supports it and your organization's access to accessibility mode.
      - `device_class` 'phone', required: The kind of device.
      - `ownership` 'dedicated' | 'shared': dedicated: one of your organization's phones, the one phone_id names or any free one. shared: a phone from the shared fleet. Defaults to dedicated when phone_id is set, else shared.
      - `phone_id` string: A dedicated phone of your organization to run on. Leave out for any of yours (ownership dedicated) or a shared phone.
      - `platform` 'android': The device's platform (default android).
    - `task` string: An agent-mode run's task: the ad hoc task, or the agent's instructions.
    - `telemetry_enabled` boolean: An ad hoc run's own telemetry choice; absent takes the default (on), and a saved agent's run takes the agent's.
    - `timeout_seconds` integer: Longest the run may take, in seconds.
    - `trace_expired_at` string, date-time: When the trace recording was deleted.
    - `trigger` 'manual' | 'scheduled' | 'api', required: Trigger identifies how the run was initiated.
    - `turn` integer: An agent-mode run's current turn, from 1.
    - `turns` RunTurn[], nullable: Every turn of an agent-mode run, oldest first: the task, then each follow-up sent with :sendMessage.
      - `completed_at` string, date-time: When the turn ended.
      - `error` string: Why the turn failed.
      - `message` string: The message that opened the turn. Absent on turn 1, which works through the run's task.
      - `model` string: The model the turn's steps called.
      - `output` unknown
      - `result_text` string: The turn's result in a sentence.
      - `session_id` string: The phone session the turn ran in.
      - `started_at` string, date-time: When the turn started.
      - `status` 'queued' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled', required: The turn's status.
      - `turn` integer, required: The turn's number, from 1.
      - `usage` RunTurnUsage: What one turn's model steps used.
        - `completion_tokens` integer, required: Completion tokens across those steps.
        - `cost_microdollars` integer, required: What those steps cost, in microdollars.
        - `last_step` integer: The number of the turn's last step, answered or not: GET /runs/{run_id}/steps reads the turn from the step after the turn before's.
        - `model_steps` integer, required: Model steps that got an answer.
        - `prompt_tokens` integer, required: Prompt tokens across those steps.
    - `updated_at` string, date-time, required: Timestamp of the last update to the run record.
    - `usage` RunUsage: What a run's model steps used.
      - `completion_tokens` integer, required: Completion tokens across those steps.
      - `cost_microdollars` integer, required: What those steps cost, in microdollars.
      - `model_steps` integer, required: Model steps that got an answer.
      - `prompt_tokens` integer, required: Prompt tokens across those steps.
    - `user_id` string, uuid, required: User who initiated the run.
    - `variables` object: The run's inputs. Deleted once the finished run is older than the plan's run data retention window (30 days by default).
    - `video_url` string: URL for the run recording video.

## Other responses

- `400`: Bad Request
- `402`: Payment Required
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-11-01** `80de09d0e643`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/axilioai/apis/axilio-api/changes/runs:batchCreate/post.md)

---

[API](https://skmtc.dev/axilioai/apis/axilio-api.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api/revisions/80de09d0e643?raw)