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

# POST /v1/traces/:id/complete — finalize a trace

> Set a trace's terminal status and output summary, then queue it for analysis. Called automatically by session.complete() and session.fail() in the SDK.

The complete endpoint finalizes a trace by setting its terminal status, recording the output or error summary, and computing the total duration. Once a trace reaches `"completed"` or `"errored"` status, the analysis worker picks it up and generates the post-trade autopsy visible in the dashboard.

```
POST https://ingest.mortem.dev/v1/traces/:id/complete
```

If you are using the SDK, you do not need to call this endpoint directly. `session.complete(outputSummary)` and `session.fail(error)` call it for you as part of the session lifecycle. Use this endpoint when you are calling the Ingest API directly or need to finalize a trace from outside the process that created it.

## Path parameters

<ParamField path="id" type="string" required>
  The trace ID to finalize. This must be the ID of a trace that was previously created through the batch endpoint and belongs to the agent identified by your API key. Returns `404` if the trace is not found or does not belong to your agent.
</ParamField>

## Request headers

| Header          | Value                     | Required            |
| --------------- | ------------------------- | ------------------- |
| `Authorization` | `Bearer <MORTEM_API_KEY>` | Yes                 |
| `Content-Type`  | `application/json`        | When sending a body |

## Request body

The request body is optional. Send it as JSON to write output or error information alongside the status update. If you omit the body entirely, the trace is marked `"completed"` with the current server time as `endedAt`.

<ParamField body="status" type="string" default="completed">
  The terminal status for the trace. Use `"completed"` for a successful run and `"errored"` for a run that ended in a failure. Accepted values are `"completed"`, `"errored"`, `"running"`, and `"timeout"`.

  <Note>
    Only traces with status `"completed"` or `"errored"` are queued for LLM analysis. Finalizing a trace with any other status skips the analysis step.
  </Note>
</ParamField>

<ParamField body="outputSummary" type="string">
  A human-readable description of what the agent produced or decided. This appears in the dashboard trace header and is used as context by the analysis worker. Pass `null` to leave the field empty.

  ```json theme={null}
  { "outputSummary": "Decided not to swap — price impact too high at 2.3%" }
  ```
</ParamField>

<ParamField body="errorMessage" type="string">
  The error message or stringified exception when `status` is `"errored"`. The analysis worker uses this alongside event data to diagnose what went wrong. Pass `null` to clear a previously set value.
</ParamField>

<ParamField body="endedAt" type="string">
  ISO 8601 datetime string for when the trace ended. Defaults to the current server time if omitted. Provide this when you are finalizing a trace after the fact and want the duration to reflect the actual wall-clock time.
</ParamField>

## Response

On success the endpoint returns `200 OK` with the trace ID.

```json theme={null}
{ "traceId": "01J8XKZP4N0000000000000000" }
```

## Example

<CodeGroup>
  ```bash curl — completed run theme={null}
  curl -X POST https://ingest.mortem.dev/v1/traces/01J8XKZP4N0000000000000000/complete \
    -H "Authorization: Bearer $MORTEM_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "completed",
      "outputSummary": "Decided not to swap — price impact too high at 2.3%"
    }'
  ```

  ```bash curl — errored run theme={null}
  curl -X POST https://ingest.mortem.dev/v1/traces/01J8XKZP4N0000000000000000/complete \
    -H "Authorization: Bearer $MORTEM_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "errored",
      "errorMessage": "RPC call to getLatestBlockhash timed out after 5000ms"
    }'
  ```

  ```json response theme={null}
  {
    "traceId": "01J8XKZP4N0000000000000000"
  }
  ```
</CodeGroup>

<Warning>
  The complete endpoint verifies that the trace belongs to the agent associated with your API key. Attempting to finalize a trace owned by a different agent returns `404`, not `403`, to avoid leaking trace existence information.
</Warning>