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

# Run an agent task

> Run a predefined browser task and inspect its result.

`GET /v1/agent/tasks` lists available task names and parameter schemas. `POST /v1/agent` runs one task in an existing session.

With `TILION_API_KEY` and `TILION_SESSION_ID` set, this example reads the heading from a public test page.

```python Python theme={"dark"}
import os
import requests

response = requests.post(
    "https://back.tilion.dev/v1/agent",
    headers={"Authorization": f"Bearer {os.environ['TILION_API_KEY']}"},
    json={
        "session_id": os.environ["TILION_SESSION_ID"],
        "task": "wait_and_extract",
        "params": {
            "url": "https://httpbin.org/html", "wait_selector": "h1",
            "fields": {"heading": "h1"}, "timeout_ms": 10000,
        },
    }, timeout=330,
)
response.raise_for_status()
result = response.json()
if not result.get("ok"):
    raise RuntimeError(result)
print(result["data"]["heading"])
```

```javascript Node.js theme={"dark"}
const response = await fetch("https://back.tilion.dev/v1/agent", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TILION_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    session_id: process.env.TILION_SESSION_ID,
    task: "wait_and_extract",
    params: {
      url: "https://httpbin.org/html", wait_selector: "h1",
      fields: { heading: "h1" }, timeout_ms: 10000,
    },
  }), signal: AbortSignal.timeout(330_000),
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (!result.ok) throw new Error(JSON.stringify(result));
console.log(result.data.heading);
```

```bash curl theme={"dark"}
# Requires jq.
curl --fail-with-body https://back.tilion.dev/v1/agent \
  -H "Authorization: Bearer $TILION_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg sid "$TILION_SESSION_ID" \
    '{session_id: $sid, task: "wait_and_extract", params: {
      url: "https://httpbin.org/html", wait_selector: "h1",
      fields: {heading: "h1"}, timeout_ms: 10000
    }}')"
```

The example returns `Herman Melville - Moby-Dick` in `data.heading`. The response also contains a `steps` trace and an `error` field.

> [!NOTE]
>
> A task can return HTTP `200` with `ok: false`. With `async_mode: true`, the initial `ok: false` and `status: "pending"` indicate that work is still running. Poll the returned `job_id` for the task result.

Tasks leave the session open. Close it after processing the result. See [Agent tasks](https://docs.tilion.dev/automation/agent-tasks.md) for the catalogue and approval handling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.