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

> Push token counts and tool usage to the platform.

`Task.areport_metrics` records the task's token usage, tool calls, and execution outcome to the platform's metrics store. The `@on_task` runtime calls this automatically at the end of every handler if `task.tokens` is set, so you only need to invoke it directly when you're driving a task outside the runtime.

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

task.tokens = Tokens(prompt_tokens=2_140, completion_tokens=380)
task.used_tools = ["web_search", "fetch_pdf"]
task.duration = 4.7

await task.areport_metrics()
```

<Note>
  `task.tokens` must be set before calling `areport_metrics`. The method raises `ValueError` if `tokens` is missing.
</Note>

### Parameters

| Parameter       | Type            | Required | Description                                                                         |
| --------------- | --------------- | -------- | ----------------------------------------------------------------------------------- |
| `configuration` | `Configuration` | No       | Override SDK config. Falls back to `task.configuration`, then env-derived defaults. |

### Returns

`None`.

## What gets reported

The metrics report includes:

* `execution_id`: task id.
* `source`: task source.
* `memory_thread_id`: same as task id (memory and execution share an id).
* `task`: input text (`task.input.text`).
* `status`: current `task.status`.
* `internal_status`: current `task.internal_status`.
* `ai_model`: fixed to `"xpander"`.
* `api_calls_made`: tool names from `task.used_tools` (or `[]` for orchestration tasks with `return_metrics=True`).
* `result`: final result string.
* `llm_tokens`: token counts wrapped in `ExecutionTokens(worker=task.tokens)`.

## Examples

### Inside a custom event loop

If you're driving an agent without `@on_task`, report metrics manually before returning to the caller:

```python theme={"dark"}
from xpander_sdk import Backend, Tokens
from xpander_sdk.modules.tasks.sub_modules.task import Task

backend = Backend()
task = await backend.ainvoke_agent(agent_id="agent-123", prompt="...")

# ... run the agent yourself, track tokens ...

task.tokens = Tokens(prompt_tokens=1_500, completion_tokens=320)
task.used_tools = ["search", "summarize"]
task.duration = 3.1

await task.areport_metrics()
```

This makes the run show up in the dashboard with proper token accounting.

### Sync version

```python theme={"dark"}
task.report_metrics()
```

## Errors

Raises [`ModuleException`](/developers/sdk-reference/error-handling) on persistence failures, or `ValueError` if `task.tokens` is `None`.