Skip to main content
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

GET /api/traces
Returns every trace in a project, newest first.

​
Query parameters

​
projectSlug
string
The project slug. Required if projectId is not provided.
​
projectId
string
The project UUID. Required if projectSlug is not provided.

​
Response

{
  "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

curl "https://app.artanis.ai/api/traces?projectSlug=my-project" \
  -H "x-api-key: $ARTANIS_API_KEY" \
  -H "x-org-slug: my-org"

​
Get a trace with spans and feedback

GET /api/traces/{traceId}
Returns a single trace along with all its spans and all feedback recorded against it.

​
Path parameters

​
traceId
string
required
The trace UUID.

​
Response

{
  "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.
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).

​
Delete a trace

DELETE /api/traces/{traceId}
Removes a trace, its spans, and its feedback. Deleted traces stop appearing in all reads.

​
Path parameters

​
traceId
string
required
The trace UUID.

​
Response

{
  "id": "uuid"
}
Returns 404 Not Found if no trace with the given ID exists in the caller’s organization.

​
Example

curl -X DELETE "https://app.artanis.ai/api/traces/$TRACE_ID" \
  -H "x-api-key: $ARTANIS_API_KEY" \
  -H "x-org-slug: my-org"