> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcell.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Task

> Run a natural language task on a session

## Path parameters

| Parameter    | Type   | Description                                |
| ------------ | ------ | ------------------------------------------ |
| `session_id` | string | The session ID (must be in `ready` status) |

## Request body

| Field       | Type    | Required | Description                                            |
| ----------- | ------- | -------- | ------------------------------------------------------ |
| `task`      | string  | Yes      | Plain English instruction for the AI agent             |
| `max_steps` | integer | No       | Maximum actions the agent can take (1-200, default 20) |

```bash theme={null}
curl -X POST https://agentcell.live/api/sessions/SESSION_ID/agent/task \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"task": "Search DuckDuckGo for the weather in Tokyo"}'
```

## Response

```json theme={null}
{
  "status": "completed",
  "summary": "Successfully searched DuckDuckGo for the weather in Tokyo. The current temperature is 18°C with partly cloudy skies.",
  "steps": [
    {
      "tool": "open_app",
      "args": {"package": "org.nicoco.nicobrowser"},
      "ok": true
    },
    {
      "tool": "click",
      "args": {"index": 3},
      "ok": true
    }
  ]
}
```

## Response fields

| Field     | Type   | Description                                 |
| --------- | ------ | ------------------------------------------- |
| `status`  | string | `"completed"` or `"failed"`                 |
| `summary` | string | Human-readable description of what happened |
| `steps`   | array  | List of actions the agent took              |

## Error responses

| Code | Meaning                               |
| ---- | ------------------------------------- |
| 402  | Trial expired — subscribe to continue |
| 404  | Session not found                     |
| 409  | Session not ready (still booting)     |

## Tips

* **DuckDuckGo over Google** — Google blocks cloud IPs with reCAPTCHA. Use DuckDuckGo for web searches.
* **One task at a time** — each session runs one agent task at a time. Wait for completion before sending the next.
* **Fresh sessions** — each session starts as a clean Android install. Apps and state don't persist between sessions.