Traces

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

string

The project slug. Required if projectId is not provided.

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"

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

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();

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

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

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"

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()

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",
  },
});

Getting Started

Endpoints

List traces

Query parameters

Response

Example

Get a trace with spans and feedback

Path parameters

Response

Reading evaluation outcomes

Delete a trace

Path parameters

Response

Example

​List traces

​Query parameters

​Response

​Example

​Get a trace with spans and feedback

​Path parameters

​Response

​Reading evaluation outcomes

​Delete a trace

​Path parameters

​Response

​Example

List traces

Query parameters

Response

Example

Get a trace with spans and feedback

Path parameters

Response

Reading evaluation outcomes

Delete a trace

Path parameters

Response

Example