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

# Traces

> Read traces, spans, approved outputs, and feedback

A trace represents a single run of a project's pipeline. Each trace has:

* **spans** — one per pipeline step, with the `input`, the model `output`, and (if a reviewer approved or edited it) an `approvedOutput`
* **feedback** — free-text comments left by reviewers, attached to specific spans

There is no separate feedback or evaluations endpoint. The trace detail response below is the single source of truth for both — `spans[].approvedOutput` is the human-validated output and `feedback[]` is the reviewer's commentary.

## List traces

```http theme={null}
GET /api/traces
```

Returns every trace in a project, newest first.

### Query parameters

<ParamField query="projectSlug" type="string">
  The project slug. Required if `projectId` is not provided.
</ParamField>

<ParamField query="projectId" type="string">
  The project UUID. Required if `projectSlug` is not provided.
</ParamField>

### Response

```json theme={null}
{
  "traces": [
    {
      "id": "uuid",
      "status": "completed",
      "metadata": { "user_id": "user-123" },
      "createdAt": "2026-04-08T09:00:00.000Z",
      "updatedAt": "2026-04-08T09:00:05.000Z"
    }
  ]
}
```

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl "https://app.artanis.ai/api/traces?projectSlug=my-project" \
    -H "x-api-key: $ARTANIS_API_KEY" \
    -H "x-org-slug: my-org"
  ```

  ```python Python theme={null}
  import os, requests

  r = requests.get(
      "https://app.artanis.ai/api/traces",
      params={"projectSlug": "my-project"},
      headers={
          "x-api-key": os.environ["ARTANIS_API_KEY"],
          "x-org-slug": "my-org",
      },
  )
  traces = r.json()["traces"]
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://app.artanis.ai/api/traces?projectSlug=my-project", {
    headers: {
      "x-api-key": process.env.ARTANIS_API_KEY!,
      "x-org-slug": "my-org",
    },
  });
  const { traces } = await res.json();
  ```
</CodeGroup>

## Get a trace with spans and feedback

```http theme={null}
GET /api/traces/{traceId}
```

Returns a single trace along with all its spans and all feedback recorded against it.

### Path parameters

<ParamField path="traceId" type="string" required>
  The trace UUID.
</ParamField>

### Response

```json theme={null}
{
  "id": "uuid",
  "status": "completed",
  "metadata": { "user_id": "user-123" },
  "createdAt": "2026-04-08T09:00:00.000Z",
  "updatedAt": "2026-04-08T09:00:05.000Z",
  "spans": [
    {
      "id": "uuid",
      "parentSpanId": null,
      "stepId": "classify",
      "input": { "email": "..." },
      "output": { "category": "billing" },
      "approvedOutput": { "category": "refund" },
      "promptVersionId": "uuid",
      "metadata": {},
      "createdAt": "2026-04-08T09:00:01.000Z"
    }
  ],
  "feedback": [
    {
      "id": "uuid",
      "spanId": "uuid",
      "userId": "uuid",
      "content": "Should have been classified as refund, not billing.",
      "createdAt": "2026-04-08T09:05:00.000Z"
    }
  ]
}
```

### Reading evaluation outcomes

For each span:

* If `approvedOutput` is `null`, the span has not been reviewed yet.
* If `approvedOutput` equals `output`, a reviewer accepted the original output as-is.
* If `approvedOutput` differs from `output`, a reviewer corrected the output. The corrected version is the ground truth.

`feedback[]` entries are attached to specific spans via `spanId`, so you can join them in client code to build per-step review records.

<Tip>
  To evaluate a new model or prompt against historical reviewer decisions, fetch traces, then for each span compare your
  candidate output against `approvedOutput` (falling back to `output` only when `approvedOutput` is `null`).
</Tip>

## Delete a trace

```http theme={null}
DELETE /api/traces/{traceId}
```

Removes a trace, its spans, and its feedback. Deleted traces stop appearing in all reads.

### Path parameters

<ParamField path="traceId" type="string" required>
  The trace UUID.
</ParamField>

### Response

```json theme={null}
{
  "id": "uuid"
}
```

Returns `404 Not Found` if no trace with the given ID exists in the caller's organization.

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE "https://app.artanis.ai/api/traces/$TRACE_ID" \
    -H "x-api-key: $ARTANIS_API_KEY" \
    -H "x-org-slug: my-org"
  ```

  ```python Python theme={null}
  import os, requests

  r = requests.delete(
      f"https://app.artanis.ai/api/traces/{trace_id}",
      headers={
          "x-api-key": os.environ["ARTANIS_API_KEY"],
          "x-org-slug": "my-org",
      },
  )
  r.raise_for_status()
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(`https://app.artanis.ai/api/traces/${traceId}`, {
    method: "DELETE",
    headers: {
      "x-api-key": process.env.ARTANIS_API_KEY!,
      "x-org-slug": "my-org",
    },
  });
  ```
</CodeGroup>