> ## Documentation Index > Fetch the complete documentation index at: https://docs.axilio.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start several runs > 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. Minimum role required: Member ## OpenAPI ````yaml /api-reference/openapi-backend.json post /runs:batchCreate openapi: 3.1.0 info: description: Axilio backend HTTP API. title: Axilio API version: 0.155.0 servers: - url: https://api.axilio.ai/api/v1 description: Production security: [] tags: - name: Agents - name: API Keys - name: Billing - name: Conversations - name: Files - name: Messages - name: Models - name: Organization - name: Phones - name: Runs - name: Sessions - name: Skill - name: Usage - name: Webhooks paths: /runs:batchCreate: post: tags: - Runs summary: Start several runs description: >- 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. operationId: runs_batch_create requestBody: content: application/json: schema: $ref: '#/components/schemas/AgentRunBatchCreateRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/AgentRunBatchCreateResponse' description: Created '400': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Bad Request '402': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Payment Required '403': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Forbidden '404': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Not Found '409': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Conflict '422': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Internal Server Error security: - apiKeyAuth: [] components: schemas: AgentRunBatchCreateRequest: additionalProperties: false description: Start up to 1000 runs at once. All are created or none is. properties: requests: description: The runs to start. items: $ref: '#/components/schemas/AgentRunCreateRequest' maxItems: 1000 minItems: 1 type: - array - 'null' required: - requests type: object AgentRunBatchCreateResponse: additionalProperties: false description: The runs a batch started, in request order. properties: runs: description: The runs, in request order. items: $ref: '#/components/schemas/RunResponse' type: - array - 'null' required: - runs type: object V2ErrorModel: additionalProperties: false description: >- Error response, following RFC 9457 (Problem Details for HTTP APIs). Returned with a application/problem+json content type. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/V2ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object AgentRunCreateRequest: additionalProperties: false description: 'Start a run: of a saved agent (agent_id) or ad hoc (task), not both.' properties: agent_id: description: The agent to run, with its current revision and settings. format: uuid type: string keep_alive_seconds: description: >- 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. format: int64 maximum: 3600 minimum: 0 type: integer max_cost_microdollars: description: >- Most an ad hoc run's model steps may cost, in microdollars (default 10000000). format: int64 minimum: 1 type: integer max_steps: description: Most model steps an ad hoc run may take (default 500). format: int64 maximum: 500 minimum: 1 type: integer model: description: >- An ad hoc run's model, one of GET /models (default the platform default). A saved agent's run uses the agent's. type: string network: description: >- The network an instructions run's code can reach: restricted (default) reaches the phone only; internet adds the public internet. Code runs always have internet. enum: - restricted - internet type: string output_schema: additionalProperties: {} description: >- The JSON Schema an ad hoc run's result must satisfy. A saved agent's run uses the agent's. type: object pause_timeout_seconds: description: >- Longest an ad hoc run waits paused for an answer, in seconds (default 600). format: int64 maximum: 3600 minimum: 60 type: integer recording_enabled: description: >- Record the screen of an ad hoc run (default false). A saved agent's run uses the agent's. type: boolean start_at: description: >- Start the run at this time, from a minute to 30 days ahead. Leave out to start now. format: date-time type: string start_timeout_seconds: description: >- How long the run may wait for a phone before it is cancelled (default 300). format: int64 maximum: 86400 minimum: 60 type: integer targets: description: >- The device the run drives (at most one). Leave out for a shared phone. items: $ref: '#/components/schemas/RunTarget' maxItems: 1 type: - array - 'null' task: description: >- An ad hoc task for an agent to work through a model, with nothing saved. maxLength: 20000 type: string telemetry_enabled: description: >- Emit telemetry for an ad hoc run (default true). A saved agent's run uses the agent's. type: boolean timeout_seconds: description: Longest an ad hoc run may take, in seconds (default 3600). format: int64 maximum: 3600 minimum: 1 type: integer variables: additionalProperties: {} description: The run's inputs, available to the run's code as the variables dict. type: object type: object RunResponse: additionalProperties: false description: 'A run: of a saved agent, or of an ad hoc task.' properties: agent_id: description: The agent the run is of; absent on an ad hoc run. format: uuid type: string agent_name: description: The agent's name, on the run lists; absent on an ad hoc run. type: string cancelled_at: description: Timestamp when the run was cancelled. format: date-time type: string completed_at: description: Timestamp when the run finished. format: date-time type: string created_at: description: Timestamp when the run record was created. format: date-time type: string error: description: Why the run failed. type: string id: description: Run identifier. format: uuid type: string input_request: $ref: '#/components/schemas/RunInputRequest' description: What a paused run asks a person; answer it with :resume. keep_alive_expires_at: description: >- Until when an ended agent-mode run holds its phone: :sendMessage before then continues the run there; after it, start a new run. format: date-time type: string max_cost_microdollars: description: Most the run's model steps may cost, in microdollars. format: int64 type: integer max_steps: description: Most model steps the run may take. format: int64 type: integer mode: description: >- agent: an agent works the task through a model. code: the agent's script runs. enum: - agent - code type: string model: description: The model the run's steps call, one of GET /models. type: string network: description: >- The network the run's code can reach: restricted reaches the phone only; internet adds the public internet. enum: - restricted - internet type: string output: description: The run's result, which satisfies its output_schema. output_schema: description: The JSON Schema the run's result must satisfy. pause_timeout_seconds: description: Longest the run waits paused for an answer, in seconds. format: int64 type: integer phone_id: description: Phone executing the run. type: string recording_enabled: description: >- An ad hoc run's own recording choice; absent takes the default (off), and a saved agent's run takes the agent's. type: boolean repair: $ref: '#/components/schemas/RunRepair' description: >- On a code run: whether the agent took over after the script failed, and the fix it proposed. result_text: description: A short account of the run's result. type: string revision_id: description: The agent's revision the run was pinned to when it was made. format: uuid type: string run_metadata: additionalProperties: {} description: Arbitrary metadata attached to the run. type: object schedule_id: description: The schedule that started the run, if one did. format: uuid type: string session_id: description: Session associated with this run. format: uuid type: string start_at: description: >- When the run was booked to start; absent for a run started on request. format: date-time type: string start_timeout_seconds: description: How long the queued run may wait for a phone before auto-cancel. format: int64 type: integer started_at: description: Timestamp when the run began executing. format: date-time type: string status: description: >- Current lifecycle state of the run. paused: the run waits on a person; see input_request. enum: - scheduled - queued - running - paused - completed - failed - cancelled type: string stream_url: description: >- 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. type: string success: description: Whether the run completed without error. type: boolean targets: description: The device the run drives. items: $ref: '#/components/schemas/RunTarget' type: - array - 'null' task: description: >- An agent-mode run's task: the ad hoc task, or the agent's instructions. type: string telemetry_enabled: description: >- An ad hoc run's own telemetry choice; absent takes the default (on), and a saved agent's run takes the agent's. type: boolean timeout_seconds: description: Longest the run may take, in seconds. format: int64 type: integer trace_expired_at: description: When the trace recording was deleted. format: date-time type: string trigger: description: Trigger identifies how the run was initiated. enum: - manual - scheduled - api type: string turn: description: An agent-mode run's current turn, from 1. format: int64 type: integer turns: description: >- Every turn of an agent-mode run, oldest first: the task, then each follow-up sent with :sendMessage. items: $ref: '#/components/schemas/RunTurn' type: - array - 'null' updated_at: description: Timestamp of the last update to the run record. format: date-time type: string usage: $ref: '#/components/schemas/RunUsage' description: What the run's model steps used, across its turns. user_id: description: User who initiated the run. format: uuid type: string variables: additionalProperties: {} description: >- The run's inputs. Deleted once the finished run is older than the plan's run data retention window (30 days by default). type: object video_url: description: URL for the run recording video. type: string required: - id - mode - user_id - status - trigger - created_at - updated_at type: object V2ErrorDetail: additionalProperties: false description: >- One specific problem within an error response, locating the offending part of the request. properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object RunTarget: additionalProperties: false description: The device a run drives. Phones only for now, Android only. properties: capabilities: $ref: '#/components/schemas/RunTargetCapabilities' description: What the run needs of the phone. device_class: description: The kind of device. enum: - phone type: string ownership: description: >- 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. enum: - dedicated - shared type: string phone_id: description: >- A dedicated phone of your organization to run on. Leave out for any of yours (ownership dedicated) or a shared phone. type: string platform: description: The device's platform (default android). enum: - android type: string required: - device_class type: object RunInputRequest: additionalProperties: false description: 'What a paused run asks a person: answer it by id to resume the run.' properties: created_at: description: When the run paused. format: date-time type: string expires_at: description: >- 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. format: date-time type: string id: description: The input request's id, which a resume names. format: uuid type: string message: description: The question, for the person answering. type: string reason: description: Why the run paused. enum: - one_time_code_required - approval_required - choice_required - challenge_blocked - step_check_failed - caller_requested type: string requested_by: description: >- agent: the agent asked. code: the script asked, or failed with on_failure ask. caller: the run was paused through the API. enum: - agent - code - caller type: string response_schema: additionalProperties: {} description: The JSON Schema the answer must satisfy. Absent takes any answer. type: object required: - id - requested_by - reason - created_at - expires_at type: object RunRepair: additionalProperties: false description: >- A code run's repair: the agent took over after the script failed and finished the task from the live screen. properties: proposed_revision_id: description: >- The fixed revision the repair proposed, waiting to be promoted. Absent when a fix for the revision was already waiting. format: uuid type: string repaired: description: The script failed and the agent took over. type: boolean required: - repaired type: object RunTurn: additionalProperties: false description: >- One turn of an agent-mode run: what opened it, how it ended, and what it used. properties: completed_at: description: When the turn ended. format: date-time type: string error: description: Why the turn failed. type: string message: description: >- The message that opened the turn. Absent on turn 1, which works through the run's task. type: string model: description: The model the turn's steps called. type: string output: description: The turn's result, matching the run's output_schema. result_text: description: The turn's result in a sentence. type: string session_id: description: The phone session the turn ran in. type: string started_at: description: When the turn started. format: date-time type: string status: description: The turn's status. enum: - queued - running - paused - completed - failed - cancelled type: string turn: description: The turn's number, from 1. format: int64 type: integer usage: $ref: '#/components/schemas/RunTurnUsage' description: What the turn's model steps used. required: - turn - status type: object RunUsage: additionalProperties: false description: What a run's model steps used. properties: completion_tokens: description: Completion tokens across those steps. format: int64 type: integer cost_microdollars: description: What those steps cost, in microdollars. format: int64 type: integer model_steps: description: Model steps that got an answer. format: int64 type: integer prompt_tokens: description: Prompt tokens across those steps. format: int64 type: integer required: - model_steps - prompt_tokens - completion_tokens - cost_microdollars type: object RunTargetCapabilities: additionalProperties: false description: What a run needs of its device. properties: accessibility: description: >- Run in accessibility mode, which needs a phone that supports it and your organization's access to accessibility mode. type: boolean type: object RunTurnUsage: additionalProperties: false description: What one turn's model steps used. properties: completion_tokens: description: Completion tokens across those steps. format: int64 type: integer cost_microdollars: description: What those steps cost, in microdollars. format: int64 type: integer last_step: description: >- 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. format: int64 type: integer model_steps: description: Model steps that got an answer. format: int64 type: integer prompt_tokens: description: Prompt tokens across those steps. format: int64 type: integer required: - model_steps - prompt_tokens - completion_tokens - cost_microdollars type: object securitySchemes: apiKeyAuth: description: Customer API key (axl_ prefix). in: header name: X-Axilio-Api-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.