--- title: "Pause a run" method: POST path: "/runs/{run_id}:pause" tags: ["Runs"] --- # Pause a run `POST /runs/{run_id}:pause` ## Request - Base URL: `https://api.axilio.ai/api/v1` - URL: `https://api.axilio.ai/api/v1/runs/{run_id}:pause` - Auth: API key in header `X-Axilio-Api-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Asks a running run to pause for a person, with reason caller_requested. An agent-mode run pauses at its next model step: a cell already running finishes first, and a run about to finish takes that step instead. A code run pauses at its script's next phone action. Returns the run as it is: it reads paused, with its input_request, once the pause lands, and run.paused fires then. A run that is not running is 409. ## Path parameters - `run_id` string, uuid, required: The run's id. ## Response `202` Accepted - RunResponse: A run: of a saved agent, or of an ad hoc task. - `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 network the run's code can reach: 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 - `403`: Forbidden - `404`: Not Found - `409`: Conflict - `422`: Unprocessable Entity - `500`: Internal Server Error ## Changes - **2026-11-02** `62aa324803a7`: 1 info - endpoint added [Operation history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/runs/:run_id:pause/post.md) --- [API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api-2/revisions/62aa324803a7?raw)