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

# report_external_task

> Class-method form of recording an externally-executed task.

`Task.areport_external_task` is the `@classmethod` version of [`Backend.areport_external_task`](/developers/sdk-reference/backend/report-external-task). It logs a task that was executed outside the xpander.ai runtime so it appears in task history and metrics.

Use this form when you don't have a `Backend` instance in scope but do have a `Configuration`.

```python theme={"dark"}
from xpander_sdk import Task, Tokens, Configuration

config = Configuration()  # picks up env vars

task = await Task.areport_external_task(
    configuration=config,
    agent_id="agent-123",
    id="ext-job-9921",
    input="Summarize Q4 earnings",
    result="Q4 revenue grew 22% YoY, driven by ...",
    tokens=Tokens(prompt_tokens=2_140, completion_tokens=380),
    duration=4.7,
    used_tools=["web_search", "fetch_pdf"],
    is_success=True,
)
```

### Parameters

| Parameter       | Type            | Required | Default               | Description                                                         |
| --------------- | --------------- | -------- | --------------------- | ------------------------------------------------------------------- |
| `configuration` | `Configuration` | No       | New `Configuration()` | SDK config (api\_key + organization\_id).                           |
| `agent_id`      | `str`           | Yes      | –                     | Agent the run belongs to.                                           |
| `id`            | `str`           | No       | `None`                | External task id. Re-using the same id updates the existing record. |
| `input`         | `str`           | No       | `None`                | Run input.                                                          |
| `llm_response`  | `Any`           | No       | `None`                | Raw provider response. Stored verbatim.                             |
| `tokens`        | `Tokens`        | No       | `None`                | Token usage.                                                        |
| `is_success`    | `bool`          | No       | `True`                | Pass/fail.                                                          |
| `result`        | `str`           | No       | `None`                | Final result.                                                       |
| `duration`      | `float`         | No       | `0`                   | Wall-clock seconds.                                                 |
| `used_tools`    | `list[str]`     | No       | `[]`                  | Tool names.                                                         |

### Returns `Task`

The platform-side `Task` after persistence. Carries the `id`, `status`, and timestamps assigned by the cloud.

## When to use this vs. `Backend.areport_external_task`

Functionally identical. `Backend.areport_external_task` is more discoverable (it sits next to the other Backend methods you'd be using); this classmethod is convenient when you don't want to instantiate `Backend`.

```python theme={"dark"}
# Equivalent ways to record an external run:

# 1. Backend
backend = Backend(configuration=config)
await backend.areport_external_task(agent_id="agent-123", id="ext-001", ...)

# 2. Task classmethod
await Task.areport_external_task(configuration=config, agent_id="agent-123", id="ext-001", ...)
```

See the [`Backend` page](/developers/sdk-reference/backend/report-external-task) for typical usage patterns (idempotent updates, failure reporting).

## Sync version

```python theme={"dark"}
Task.report_external_task(configuration=config, agent_id="agent-123", id="ext-001", ...)
```