Run a task or an agent

POST /runs starts one run. Send a task for an ad hoc run with nothing saved, or an agent_id to run a saved agent’s current revision with its settings. The response is the run, with its id, status and stream_url. The SDKs need Python 0.23.0 or Go v0.16.0 or later.

Run an ad hoc task

An ad hoc run takes its settings in the request: model, output_schema, max_steps, max_cost_microdollars, timeout_seconds, pause_timeout_seconds, recording_enabled and telemetry_enabled. Leave them out for the defaults.

Dashboard
CLI
Python SDK
Go SDK
REST API

Open Run a task.
Describe the task, for example “Open Settings and report the Android version”.
Optionally, use the options under the box to pick the phone, a result schema, the model and the limits.
Press Enter. The run’s page opens with the phone and the agent’s steps.

axilio runs start --task "Open Settings, go to About phone, and report the Android version." --watch

--task runs the instruction without saving an agent. Pass --task or --agent, not both. The run takes one of your dedicated phones, whichever is free, and --phone-id pins a specific one.

from axilio.platform import Client

client = Client()
run = client.runs.start(
    task="Open Settings, go to About phone, and report the Android version.",
    targets=[{"device_class": "phone", "ownership": "dedicated"}],
)
print(run.id)

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    platformgo "github.com/axilioai/platform-go"
    "github.com/axilioai/platform-go/client"
    "github.com/axilioai/platform-go/option"
)

func main() {
    api := client.NewClient(
        option.WithAPIKey(os.Getenv("AXILIO_API_KEY")),
        option.WithBaseURL("https://api.axilio.ai/api/v1"),
    )
    task := "Open Settings, go to About phone, and report the Android version."
    ownership := platformgo.RunTargetOwnershipDedicated
    run, err := api.Runs.Start(context.Background(), &platformgo.AgentRunCreateRequest{
        Task: &task,
        Targets: []*platformgo.RunTarget{{
            DeviceClass: platformgo.RunTargetDeviceClassPhone,
            Ownership:   &ownership,
        }},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(run.ID)
}

REST API References:

Start a run: POST /runs

Examples use Bash. To run them in PowerShell, see Run the curl examples on Windows.

curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.axilio.ai/api/v1/runs \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "task": "Open Settings, go to About phone, and report the Android version.",
    "output_schema": {
      "type": "object",
      "properties": {"android_version": {"type": "string"}},
      "required": ["android_version"]
    },
    "max_cost_microdollars": 2000000
  }'

Run a saved agent

A saved agent’s run uses the agent’s current revision, model, output schema, limits and data settings.

Dashboard
CLI
REST API

Open Agents and select the agent.
Click Run.
Optionally, choose the phone and, for an instructions agent, Internet: Phone only (default) or Phone and the internet. Then start the run.

axilio runs start --agent agent_123 --variables '{"query": "coffee"}' --watch

--watch follows the run to its end, like axilio runs watch. The run takes one of your dedicated phones, whichever is free. --phone-id pins a specific one, and --start-timeout sets how long it may wait.

REST API References:

Start a run: POST /runs

Examples use Bash. To run them in PowerShell, see Run the curl examples on Windows.

curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.axilio.ai/api/v1/runs \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_id": "agent_123",
    "variables": {"query": "coffee"},
    "start_timeout_seconds": 300
  }'

variables is a JSON object. The run’s code reads it as the variables dict, in both code and agent-mode runs. start_timeout_seconds is how long a queued run may wait for a phone before Axilio cancels it, from 60 to 86,400 seconds. The default is 300.

Axilio stores and delivers run variables as plaintext. Do not put passwords, API keys, or other secrets in variables.

Axilio keeps a finished run’s variables for your plan’s data retention window, 30 days unless your plan or contract sets another, then deletes them. After that, the run still reads back with its status and timings but without variables.

Choose the phone

Leave out targets to run on a shared phone. To run on one of your dedicated phones, send one target:

"targets": [{"device_class": "phone", "phone_id": "ph_123"}]

Target	Phone
No `targets`	A phone from the shared pool, billed per second. The CLI always sends a dedicated target instead.
`{"device_class": "phone", "ownership": "dedicated"}`	Any free dedicated phone of your organization.
`{"device_class": "phone", "phone_id": "ph_123"}`	That dedicated phone. It must be active, or the request returns `400`. If it is busy, the run waits for it, up to its start timeout.
`"capabilities": {"accessibility": true}`	Adds accessibility mode, which needs a phone that supports it.

A run takes at most one target.

Give the run internet access

An agent-mode run’s code reaches only the phone by default (network: "restricted"). Set network: "internet" when its code needs the public internet, for example to download a file. Code runs always have internet access, so a code agent’s run takes no network.

Keep the phone for follow-ups

After an agent-mode run’s turn ends, the run holds its phone for keep_alive_seconds, so you can send a follow-up on the same screen. The default is 120 seconds on POST /runs and 0 in a batch. The range is 0 to 3600, and 0 releases the phone as soon as the turn ends. A shared phone bills for the hold. Set keep_alive_seconds: 0 when nobody will follow up. See Pause and follow up.

Book a run for later

Set start_at to start the run at a later time instead of now. For recurring runs, use a schedule.

curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.axilio.ai/api/v1/runs \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"agent_id": "agent_123", "start_at": "2026-11-01T03:00:00Z"}'

start_at is an RFC 3339 timestamp from a minute to 30 days ahead.
A booked run reads status scheduled and trigger scheduled until it starts. Filter for it with status=scheduled.
A run starts within about 15 seconds of start_at, then waits for a phone like any queued run. start_timeout_seconds counts from then.
A booked run holds no concurrency slot while it waits.
You can cancel a booked run any time before it starts. It then never runs, and a run.cancelled webhook is sent.

Start many runs

POST /runs:batchCreate takes up to 1,000 requests, each shaped like a POST /runs body. All the runs are created, or none is, and an error names the request it is for.

REST API

REST API References:

Start several runs: POST /runs:batchCreate

Examples use Bash. To run them in PowerShell, see Run the curl examples on Windows.

curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.axilio.ai/api/v1/runs:batchCreate" \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "requests": [
      {"agent_id": "agent_123", "targets": [{"device_class": "phone", "phone_id": "ph_123"}]},
      {"agent_id": "agent_123", "targets": [{"device_class": "phone", "phone_id": "ph_456"}]},
      {"agent_id": "agent_123", "variables": {"query": "tea"}}
    ]
  }'

The response lists the runs in request order.

A batch can’t name the same dedicated phone twice.

Concurrency and balance

Your plan’s concurrency limit counts running and paused runs. While your organization is at the limit, POST /runs and POST /runs:batchCreate return 409. An accepted batch’s runs beyond the limit wait in the queue for a free slot. Starting a run with a balance of zero or less returns 402. See Errors.

Get Started

Phones and Sessions

Agents and Runs

Files

Webhooks

Observability

Telemetry

Usage

Billing

Organization

Reference

Run a task or an agent

Run an ad hoc task

Run a saved agent

Choose the phone

Give the run internet access

Keep the phone for follow-ups

Book a run for later

Start many runs

Concurrency and balance

Next steps

Monitor runs

Pause and follow up

​Run an ad hoc task

​Run a saved agent

​Choose the phone

​Give the run internet access

​Keep the phone for follow-ups

​Book a run for later

​Start many runs

​Concurrency and balance

​Next steps

Monitor runs

Pause and follow up

Run an ad hoc task

Run a saved agent

Choose the phone

Give the run internet access

Keep the phone for follow-ups

Book a run for later

Start many runs

Concurrency and balance

Next steps