Tasks

A task is a plain-English instruction for a running device, such as “Sign up with test@example.com, skip the tutorial and confirm the home screen shows Welcome”. AkaPhone hands it to ARTEMIS, Google's open-source Android agent, which runs on the device's host, looks at the screen, decides on an action (tap, type, swipe, key), performs it, and repeats until it is done or gives up.

ARTEMIS runs unmodified. AkaPhone adds the device, the model key plumbing, progress events, artifacts and billing.

Bring your own model key#

ARTEMIS needs a large language model. AkaPhone does not resell tokens: you send your own provider key with each task request.

The host picks the model for the provider and profile. With the default host configuration that is:

Your provider bills you for the tokens. AkaPhone bills only the device minutes. More in Model keys.

Profiles: flash and pro#

profile selects the ARTEMIS profile:

• flash (the API default) is fast and cheap. Use it for short, direct actions: open an app, toggle a setting, read a value off the screen.
• pro plans and verifies more. Use it for multi-step flows: sign-up, checkout, anything with branches or where you need a careful final check.

One task per device#

A device runs one task at a time. Starting a second task while one is queued or running returns 409 conflict with the id of the active task. Wait for it, or cancel it with POST /v1/tasks/:id/cancel. To run tasks in parallel, use more devices.

Statuses#

queued ──▶ running ──▶ succeeded
   │          ├──────▶ failed
   └──────────┴──────▶ cancelled

If the device stops while a task is running, the host ends the task and it finishes as failed or cancelled.

Timeouts#

A task that stays queued for more than 5 minutes, or running for more than 1,900 seconds (about 31 minutes), is failed with "error": "timeout". The host itself stops ARTEMIS after 30 minutes.

Steps#

Each action ARTEMIS takes is a step with a number, a short label and its duration in milliseconds. GET /v1/tasks/:id includes them:

"steps": [
  { "n": 1, "label": "Open the Settings app", "ms": 2140 },
  { "n": 2, "label": "Tap Display", "ms": 1830 },
  { "n": 3, "label": "Turn on Dark theme", "ms": 1610 }
]

Watchers of the live stream get each step as a task.step event as it happens.

Artifacts#

When a task ends, the host uploads its artifacts. GET /v1/tasks/:id/artifacts lists them with download URLs that are valid for 15 minutes:

Artifacts are deleted after your plan's retention period: 7 days on Free, 30 on Dev, 90 on Team. Task records follow the same retention.

Writing good instructions#

• Say what done looks like. “…then confirm the cart shows 2 items” gives the agent a check to run and gives you a pass or fail.
• Ask for the answer you want back. “Report the build number exactly as shown” puts it in result.
• One flow per task. Several small tasks on the same device are easier to debug than one long one, and each gets its own video.
• Use test accounts. Do not automate accounts or services you do not own.

The task object#

{
  "id": "tsk_01m5vqsywgehe4jhva3g0r",
  "device_id": "dev_s6zr7mr4f2f1",
  "instruction": "Open Settings > About phone and report the Android version",
  "profile": "flash",
  "provider": "gemini",
  "status": "succeeded",
  "result": "Android version: 14",
  "error": null,
  "step_count": 4,
  "created_at": "2026-10-26T09:15:10.000Z",
  "started_at": "2026-10-26T09:15:11.000Z",
  "ended_at": "2026-10-26T09:15:29.000Z"
}

provider is null when you did not send X-Model-Provider. steps (the array) is present only on GET /v1/tasks/:id and on the cancel response; every response has step_count.

Full endpoint reference: Tasks API.