# Tasks

> How plain-English tasks run on a device with Google's ARTEMIS agent and your own model key; flash and pro profiles, statuses, steps, artifacts and timeouts.

Source: https://akaphone-docs.pages.dev/concepts/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](https://github.com/google/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.

| Header | Value |
|---|---|
| `X-Model-Key` | Your provider API key. Kept in memory for the duration of the request and the task, then discarded. Never written to a database, log or audit record, and never echoed back. |
| `X-Model-Provider` | `gemini` (the default when omitted), `anthropic` or `openai`. Anything else is `400 invalid_request`. |

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

| Provider | `flash` | `pro` |
|---|---|---|
| `gemini` | `gemini-2.5-flash` | `gemini-2.5-pro` |
| `anthropic` | `claude-sonnet-4-5` | `claude-sonnet-4-5` |
| `openai` | `gpt-4.1` | `gpt-4.1` |

Your provider bills you for the tokens. AkaPhone bills only the device minutes. More in [Model keys](https://akaphone-docs.pages.dev/guides/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.

> **The MCP server defaults to pro**
>
> `POST /v1/devices/:id/tasks` defaults to `flash`. The MCP tool `device_run_task` sends `pro` unless you or your agent ask for `flash`.

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

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

| Status | Meaning |
|---|---|
| `queued` | Accepted and sent to the host. |
| `running` | ARTEMIS has started. `step_count` grows as it works. |
| `succeeded` | ARTEMIS finished and reported success. `result` holds its final answer. |
| `failed` | ARTEMIS gave up, the model call failed, the host could not run it, or it timed out. `error` says why. |
| `cancelled` | You cancelled it. |

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:

```json
"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](https://akaphone-docs.pages.dev/api/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:

| File | `kind` | What it is |
|---|---|---|
| `video.mp4` | `video` | Screen recording of the whole task. |
| `before.png`, `after.png` | `screenshot` | The screen before and after. |
| `trace.tar.gz` | `trace` | The ARTEMIS trace directory. |
| `stdout.log` | `log` | ARTEMIS output, with your model key redacted. |

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

```json
{
  "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](https://akaphone-docs.pages.dev/api/tasks/).