---
title: "Send a message to a run"
method: POST
path: "/runs/{run_id}:sendMessage"
tags: ["runs"]
---

# Send a message to a run

`POST /runs/{run_id}:sendMessage`

## 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/{run_id}:sendMessage`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/axilio-api/docs/runs/:run_id:sendMessage/post.ts> (a function with typed inputs; its response is checked against the schema)

Sends a person's message to an agent-mode run. To a run that is running or paused, the run's model reads it before its next step, as a turn from the person running the task, and the run's stream carries it as a user_message event, its body the message, once the run's phone has it. A message never resumes a paused run: answer the pause with :resume. A run holds at most 20 unread messages, and the edge refuses one past that, or one that arrives as the run finishes, which may then never be read or shown. To a run that ended (completed, failed or cancelled) while it still holds its phone (keep_alive_expires_at is in the future), the message starts the run's next turn on the same phone, and the run goes back to queued. Returns the run as it is. A code run, a queued or scheduled run, a run whose hold has ended, or a run whose phone cannot take messages yet is 409; an empty message, or one over 64 KiB, is 400.

## Path parameters

- `run_id` string, uuid, required: The run's id.

## Request body

- AgentRunSendMessageRequest: A message for an agent-mode run's model: sent while the run works or is paused it steers the run; sent once it has completed or failed it starts the run's next turn.
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `message` string, required: What the person says to the run's model. Required, at most 64 KiB.
  - `model` string: The next turn's model, one of GET /models, for a message to a completed or failed run (default the run's). Not taken while the run works.

## Response `202`

Accepted

- RunResponse: A run: of a saved agent, or of an ad hoc task.
  - `$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
- `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/:run_id:sendMessage/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)