Runs

Send a message to a run

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 a message past that is refused, 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.

POST

runs

{run_id}

:sendMessage

Send a message to a run

curl --request POST \
  --url https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage \
  --header 'Content-Type: application/json' \
  --header 'X-Axilio-Api-Key: <api-key>' \
  --data '
{
  "message": "<string>",
  "model": "<string>"
}
'

import requests

url = "https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage"

payload = {
    "message": "<string>",
    "model": "<string>"
}
headers = {
    "X-Axilio-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Axilio-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({message: '<string>', model: '<string>'})
};

fetch('https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'message' => '<string>',
    'model' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Axilio-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage"

	payload := strings.NewReader("{\n  \"message\": \"<string>\",\n  \"model\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Axilio-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage")
  .header("X-Axilio-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"message\": \"<string>\",\n  \"model\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Axilio-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"message\": \"<string>\",\n  \"model\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "created_at": "2023-11-07T05:31:56Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "mode": "agent",
  "status": "scheduled",
  "trigger": "manual",
  "updated_at": "2023-11-07T05:31:56Z",
  "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_name": "<string>",
  "cancelled_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "error": "<string>",
  "input_request": {
    "created_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reason": "one_time_code_required",
    "requested_by": "agent",
    "message": "<string>",
    "response_schema": {}
  },
  "keep_alive_expires_at": "2023-11-07T05:31:56Z",
  "max_cost_microdollars": 123,
  "max_steps": 123,
  "model": "<string>",
  "network": "restricted",
  "output": "<unknown>",
  "output_schema": "<unknown>",
  "pause_timeout_seconds": 123,
  "phone_id": "<string>",
  "recording_enabled": true,
  "repair": {
    "repaired": true,
    "proposed_revision_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "result_text": "<string>",
  "revision_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "run_metadata": {},
  "schedule_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "start_at": "2023-11-07T05:31:56Z",
  "start_timeout_seconds": 123,
  "started_at": "2023-11-07T05:31:56Z",
  "stream_url": "<string>",
  "success": true,
  "targets": [
    {
      "device_class": "phone",
      "capabilities": {
        "accessibility": true
      },
      "ownership": "dedicated",
      "phone_id": "<string>",
      "platform": "android"
    }
  ],
  "task": "<string>",
  "telemetry_enabled": true,
  "timeout_seconds": 123,
  "trace_expired_at": "2023-11-07T05:31:56Z",
  "turn": 123,
  "turns": [
    {
      "status": "queued",
      "turn": 123,
      "completed_at": "2023-11-07T05:31:56Z",
      "error": "<string>",
      "message": "<string>",
      "model": "<string>",
      "output": "<unknown>",
      "result_text": "<string>",
      "session_id": "<string>",
      "started_at": "2023-11-07T05:31:56Z",
      "usage": {
        "completion_tokens": 123,
        "cost_microdollars": 123,
        "model_steps": 123,
        "prompt_tokens": 123,
        "last_step": 123
      }
    }
  ],
  "usage": {
    "completion_tokens": 123,
    "cost_microdollars": 123,
    "model_steps": 123,
    "prompt_tokens": 123
  },
  "variables": {},
  "video_url": "<string>"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Minimum role required: Member

Authorizations

X-Axilio-Api-Key

string

header

required

Customer API key (axl_ prefix).

Path Parameters

run_id

string<uuid>

required

The run's id.

Body

application/json

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.

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

Accepted

A run: of a saved agent, or of an ad hoc task.

created_at

string<date-time>

required

Timestamp when the run record was created.

string<uuid>

required

Run identifier.

mode

enum<string>

required

agent: an agent works the task through a model. code: the agent's script runs.

Available options:

agent,

code

status

enum<string>

required

Current lifecycle state of the run. paused: the run waits on a person; see input_request.

Available options:

scheduled,

queued,

running,

paused,

completed,

failed,

cancelled

trigger

enum<string>

required

Trigger identifies how the run was initiated.

Available options:

manual,

scheduled,

api

updated_at

string<date-time>

required

Timestamp of the last update to the run record.

user_id

string<uuid>

required

User who initiated the run.

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.

error

string

Why the run failed.

input_request

object

What a paused run asks a person; answer it with :resume.

Show child attributes

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<int64>

Most the run's model steps may cost, in microdollars.

max_steps

integer<int64>

Most model steps the run may take.

model

string

The model the run's steps call, one of GET /models.

network

enum<string>

The network the run's code can reach: restricted reaches the phone only; internet adds the public internet.

Available options:

restricted,

internet

output

any

The run's result, which satisfies its output_schema.

output_schema

any

The JSON Schema the run's result must satisfy.

pause_timeout_seconds

integer<int64>

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

object

On a code run: whether the agent took over after the script failed, and the fix it proposed.

Show child attributes

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.

Show child attributes

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<int64>

How long the queued run may wait for a phone before auto-cancel.

started_at

string<date-time>

Timestamp when the run began executing.

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

object[] | null

The device the run drives.

Show child attributes

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<int64>

Longest the run may take, in seconds.

trace_expired_at

string<date-time>

When the trace recording was deleted.

turn

integer<int64>

An agent-mode run's current turn, from 1.

turns

object[] | null

Every turn of an agent-mode run, oldest first: the task, then each follow-up sent with :sendMessage.

Show child attributes

usage

object

What the run's model steps used, across its turns.

Show child attributes

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).

Show child attributes

video_url

string

URL for the run recording video.

Send a message to a run

curl --request POST \
  --url https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage \
  --header 'Content-Type: application/json' \
  --header 'X-Axilio-Api-Key: <api-key>' \
  --data '
{
  "message": "<string>",
  "model": "<string>"
}
'

import requests

url = "https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage"

payload = {
    "message": "<string>",
    "model": "<string>"
}
headers = {
    "X-Axilio-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Axilio-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({message: '<string>', model: '<string>'})
};

fetch('https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'message' => '<string>',
    'model' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Axilio-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage"

	payload := strings.NewReader("{\n  \"message\": \"<string>\",\n  \"model\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Axilio-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage")
  .header("X-Axilio-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"message\": \"<string>\",\n  \"model\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.axilio.ai/api/v1/runs/{run_id}:sendMessage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Axilio-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"message\": \"<string>\",\n  \"model\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "created_at": "2023-11-07T05:31:56Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "mode": "agent",
  "status": "scheduled",
  "trigger": "manual",
  "updated_at": "2023-11-07T05:31:56Z",
  "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_name": "<string>",
  "cancelled_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "error": "<string>",
  "input_request": {
    "created_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reason": "one_time_code_required",
    "requested_by": "agent",
    "message": "<string>",
    "response_schema": {}
  },
  "keep_alive_expires_at": "2023-11-07T05:31:56Z",
  "max_cost_microdollars": 123,
  "max_steps": 123,
  "model": "<string>",
  "network": "restricted",
  "output": "<unknown>",
  "output_schema": "<unknown>",
  "pause_timeout_seconds": 123,
  "phone_id": "<string>",
  "recording_enabled": true,
  "repair": {
    "repaired": true,
    "proposed_revision_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "result_text": "<string>",
  "revision_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "run_metadata": {},
  "schedule_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "start_at": "2023-11-07T05:31:56Z",
  "start_timeout_seconds": 123,
  "started_at": "2023-11-07T05:31:56Z",
  "stream_url": "<string>",
  "success": true,
  "targets": [
    {
      "device_class": "phone",
      "capabilities": {
        "accessibility": true
      },
      "ownership": "dedicated",
      "phone_id": "<string>",
      "platform": "android"
    }
  ],
  "task": "<string>",
  "telemetry_enabled": true,
  "timeout_seconds": 123,
  "trace_expired_at": "2023-11-07T05:31:56Z",
  "turn": 123,
  "turns": [
    {
      "status": "queued",
      "turn": 123,
      "completed_at": "2023-11-07T05:31:56Z",
      "error": "<string>",
      "message": "<string>",
      "model": "<string>",
      "output": "<unknown>",
      "result_text": "<string>",
      "session_id": "<string>",
      "started_at": "2023-11-07T05:31:56Z",
      "usage": {
        "completion_tokens": 123,
        "cost_microdollars": 123,
        "model_steps": 123,
        "prompt_tokens": 123,
        "last_step": 123
      }
    }
  ],
  "usage": {
    "completion_tokens": 123,
    "cost_microdollars": 123,
    "model_steps": 123,
    "prompt_tokens": 123
  },
  "variables": {},
  "video_url": "<string>"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Overview

Device Control Protocol

REST API

Argus API

Send a message to a run

Authorizations

Path Parameters

Body

Response