Get traces

This page documents read endpoints for traces:

Paginated list: GET /traces
One trace by id (with spans): GET /traces/{trace_id}

Traces are created through Ingest traces. Filing/sharing metadata (name, collection, org, project) can be changed with Update trace. There is no public delete.

Get all traces (paginated)

Endpoint: GET /traces

Description

Returns a paginated list of trace summaries, ordered by start_time descending, then integer id descending. List items are summaries only — no nested spans, no resource_attributes, and no full input / output payloads (those are on the detail response). Each item includes permissions for this caller (can_edit, can_delete, can_share, can_assign_project, can_move_collection) — see Introduction — Permissions. The example is an org-shared trace you own, read with a private API key, so can_share is true (you may unshare it) and project_id is null (a private key does not receive organization project ids). With a project-scoped API key, only traces assigned to that project are returned — see API key scoping.

Parameters

page — integer, default 1, minimum 1. A page past the last page is clamped to the last page (not an empty page).
page_size — integer, default 10, between 1 and 10000.
shared — optional boolean. The value must be the word true or false, any letter case (TRUE and FALSE are valid). Surrounding whitespace is not trimmed. false returns only traces you own; true returns only traces owned by someone else that you can see; omit to return both. shared=true on a private key, or for a solo account, returns 404 ("You are not a member of an organization, so filtering to only shared resources is not available.").
search — optional string (max 255 characters). Case-insensitive substring match on the trace name (name contains the term). If the value is all digits, it also matches the integer row id exactly. If the value is hex-only (at least 8 characters, not purely decimal), it also matches the OTLP trace_id as a partial lowercase hex substring. A whitespace-only value does not filter.
data_collection_ids — optional comma-separated list of positive integers. Returns traces whose data_collection_id is one of the listed ids.
project_ids — optional comma-separated list of positive integers. Returns traces with a direct project assignment in that list. A trace that only shows a project through its collection is not included.
statuses — optional comma-separated list of ok and/or error (case-sensitive, lowercase only). ok returns traces with no span errors; error returns traces with at least one span error. When both ok and error are supplied, no status filter is applied.

Invalid tokens in data_collection_ids / project_ids (non-integers, zero, or negative values) yield 422 ("Invalid IDs (must be positive integers): ['…']"). Invalid statuses tokens yield 422 ("Invalid TraceStatusFilterEnum tokens (allowed: error, ok): ['…']"). Out-of-range page / page_size or an overlong search also yield 422. Any other shared value — including surrounding whitespace and spellings such as yes, y, t, on, 1, no, n, f, off, and 0 — yields 422 ("Value error, Value must be true or false."; detail[0].loc is ["query", "shared"]).

Error responses

401 — Authentication failed.
404 — shared=true without organization scope ("You are not a member of an organization, so filtering to only shared resources is not available.").
422 — Invalid page / page_size, overlong search, invalid data_collection_ids / project_ids, invalid statuses tokens, or invalid shared. shared accepts only true or false (any letter case).
500 — "An error occurred while retrieving traces."

Responses

200 — JSON with items and meta. Each item is a trace summary (no spans).

Example response (200)

{
  "items": [
    {
      "id": 42,
      "user": { "id": 7, "email": "ingest@example.com" },
      "author_email": "ingest@example.com",
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "name": "Agent workflow",
      "start_time": "2026-09-07T10:00:00Z",
      "duration_ms": 123.4,
      "span_count": 7,
      "error_count": 0,
      "total_tokens": 120,
      "cost_usd": "0.0012",
      "estimated_cost_usd": null,
      "data_collection_id": null,
      "org_id": 3,
      "project_id": null,
      "permissions": {
        "can_edit": true,
        "can_delete": true,
        "can_share": true,
        "can_assign_project": false,
        "can_move_collection": true
      },
      "created_at": "2026-09-07T10:00:01Z",
      "updated_at": "2026-09-07T10:00:01Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 10,
    "total_items": 1,
    "items_on_page": 1,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false,
    "next_page": null,
    "previous_page": null
  }
}

{
  "items": [
    {
      "id": 0,
      "user": { "id": 0, "email": "string" },
      "author_email": "string",
      "trace_id": "string (32-char lowercase hex OTLP trace id)",
      "name": "string",
      "start_time": "date",
      "duration_ms": "number",
      "span_count": 0,
      "error_count": 0,
      "total_tokens": "integer | null",
      "cost_usd": "string | null",
      "estimated_cost_usd": "string | null",
      "data_collection_id": "integer | null",
      "org_id": "integer | null",
      "project_id": "integer | null",
      "permissions": {
        "can_edit": "boolean",
        "can_delete": "boolean",
        "can_share": "boolean",
        "can_assign_project": "boolean",
        "can_move_collection": "boolean"
      },
      "created_at": "date",
      "updated_at": "date"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 10,
    "total_items": 1,
    "items_on_page": 1,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false,
    "next_page": "integer | null",
    "previous_page": "integer | null"
  }
}

Field notes:

id is the integer row id used by GET /traces/{trace_id} — not the hex trace_id. trace_id is the 32-char lowercase hex OTLP id. root_span_id, end_time, per-direction token counts, and full input / output are on the detail response only.
user is the owning account, or null for org-only traces. author_email is a snapshot of the API key holder's email at ingest time and is not kept in sync if the account email changes later.
Token and cost fields are null when no LLM spans reported them. cost_usd / estimated_cost_usd roll up LLM spend from the traced workflow (reported or estimated from tokens) — not the cost of evaluations you run on Aegis (see run total_cost for that). Observed and estimated spend do not double-count.
org_id present ⇒ org-shared; null ⇒ personal. project_id is the trace's direct project assignment when this key can see it. A project-scoped key also receives the collection's project when the trace has no direct assignment. A private key always receives project_id: null. The project_ids query filters on a direct assignment only, so a trace that only shows a project through its collection is not included.

Sharing rules

Private key (including an org member's private key) and solo accounts: only traces you own. That includes an org-shared trace you own. Other members' org-shared traces are hidden.
Project-scoped key: only traces assigned to that project. Unassigned traces are hidden.

curl

curl "https://api.aegisevals.ai/api/v1/traces?page=1&page_size=20" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000"

With filters:

curl "https://api.aegisevals.ai/api/v1/traces?search=agent&statuses=ok&project_ids=5&data_collection_ids=14" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000"

Get trace by id

Endpoint: GET /traces/{trace_id}

Description

Returns one trace with its spans. The response includes every field from the paginated list, plus:

root_span_id — 16-char lowercase hex OTLP root span id.
end_time — capture end timestamp.
prompt_tokens / completion_tokens — per-direction token counts when reported.
input / output — JSON values (stored JSON object/array promoted to structure; plain text stays a string).
resource_attributes — object of OTLP resource attributes (JSON-string object/array values promoted to structure), or null.
spans — array of span objects, ordered by start_time then span row id. Each span uses the full Get span field set. The example below shortens each span to identity and timing.

Parameters

Path: trace_id — the integer row id (from the list id field), not the OTLP hex trace_id.

Error responses

401 — Authentication failed.
404 — "Trace with id {trace_id} not found." — missing, or the caller cannot see it (including a project-scoped key whose project does not contain the trace). The same 404 is returned in both cases; there is no 403 on read.
422 — trace_id is not an integer.
500 — "An error occurred while retrieving the trace."

Responses

200 — JSON with the full trace object, including resource_attributes and spans.

Example response (200)

{
  "id": 42,
  "user": { "id": 7, "email": "ingest@example.com" },
  "author_email": "ingest@example.com",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "root_span_id": "00f067aa0ba902b7",
  "name": "Agent workflow",
  "start_time": "2026-09-07T10:00:00Z",
  "end_time": "2026-09-07T10:00:00.123Z",
  "duration_ms": 123.4,
  "span_count": 7,
  "error_count": 0,
  "prompt_tokens": 100,
  "completion_tokens": 20,
  "total_tokens": 120,
  "cost_usd": "0.0012",
  "estimated_cost_usd": null,
  "input": {},
  "output": {},
  "data_collection_id": null,
  "org_id": 3,
  "project_id": null,
  "permissions": {
    "can_edit": true,
    "can_delete": true,
    "can_share": true,
    "can_assign_project": false,
    "can_move_collection": true
  },
  "created_at": "2026-09-07T10:00:01Z",
  "updated_at": "2026-09-07T10:00:01Z",
  "resource_attributes": {
    "service.name": "my-service"
  },
  "spans": [
    {
      "id": 1,
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "span_id": "00f067aa0ba902b7",
      "parent_span_id": null,
      "name": "Agent workflow",
      "otel_kind": "INTERNAL",
      "span_kind": "AGENT",
      "start_time": "2026-09-07T10:00:00Z",
      "end_time": "2026-09-07T10:00:00.123Z",
      "duration_ms": 123.4,
      "status_code": "OK",
      "status_message": null
    }
  ]
}

resource_attributes is null when the trace has no stored resource attributes. See Get span for every field on a span.

Sharing rules

Same visibility as GET /traces, including permissions. This example is the same private-key owner of an org-shared trace, so can_share is true and project_id is null. A project-scoped key receives the direct project assignment, or the collection's project when the trace has none. Spans on the detail payload are visible together with the trace. Spans do not include permissions.

curl

curl "https://api.aegisevals.ai/api/v1/traces/42" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000"

Get all traces (paginated)​

Get trace by id​

Get all traces (paginated)

Get trace by id