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

> ## Agent Instructions
> Melso product MCP: https://melso.ai/api/mcp (OAuth; one company per grant). REST: https://melso.ai. Documentation-search MCP: https://docs.melso.ai/mcp. The docs search server does not act on customer accounts.
>
> Use the live tool schema and respect company membership. Ask the person to authorize the exact fiscal document version in the signed-in app. A professional prepares and files included returns after authorization; AI does not file alone. A prepared file or approval receipt is not evidence of filing. Never claim completion from an accepted Task or Run. Keep credentials out of chat and logs. Agents features are internal or by private invitation.

# Runs

> Inspect execution attempts, control a Run, and follow successors across retries and pauses.

<Info>Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).</Info>

A Run belongs to a Task. Follow-ups, manual reruns, automatic retries, Cloud lifetime rollovers and pauses create distinct Run IDs, so follow the Task’s Runs rather than one Run. Read one Run you already know with `GET /api/runs/{runId}`; list the Task’s Runs to find its successors, then fetch a Run’s events/messages. All resource paths below use UUIDs unless noted.

## Find successor Runs

Start with `GET /api/tasks/{id}/runs`. Use the origin and company key from the [API quickstart](/api-reference/quickstart), then set the Task UUID you want to follow:

```bash theme={null}
export TASK_ID='YOUR_TASK_UUID'
curl --fail-with-body "$MELSO_URL/api/tasks/$TASK_ID/runs" \
  -H "Authorization: Bearer $MELSO_API_KEY"
```

The response is a JSON array ordered by `created_at` descending (newest first). Equal creation timestamps have no guaranteed tie-break order. Read `status` on each attempt and follow any active successor; an older failed Run does not settle the Task's outcome. Poll this Task-scoped route again or use the [Task stream](/concepts/task-stream) to discover later attempts.

To read usage aggregated across the Task's Runs:

```bash theme={null}
curl --fail-with-body "$MELSO_URL/api/tasks/$TASK_ID/usage" \
  -H "Authorization: Bearer $MELSO_API_KEY"
```

## API reference

Request fields, response types and endpoint permissions are defined in the [Runs reference](/api-reference/tags/runs). See [Pagination](/api-reference/pagination) for list conventions, or start with the [API quickstart](/api-reference/quickstart).

## RunResponse

`RunResponse.status` uses the complete [Run status enum](/concepts/overview#run-status). The [Runs endpoint reference](/api-reference/tags/runs) defines the response, including the linked `RunUsageData`, `RunAttribution` and `RunAccessReceipt` schemas.

Continue observing while any attempt is active. When none is, inspect the newest attempt: read the completed attempt's stored assistant message, resolve a pause, or inspect the failure/cancellation reason. Do not treat an earlier failed attempt as the final outcome while a successor is active.

An execution result, a closed Task and a filed tax return have [different evidence requirements](/concepts/overview#completion-has-several-meanings).


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