Traces

Ingest batches of agent traces and query trace data from the dashboard API.

Traces are the primary unit of observability in AgentVista. Each trace represents a single agent run and contains one or more spans that record the operations that happened during that run.

---

Ingest a batch of traces

cURL

curl -X POST https://api.agentvista.dev/api/v1/traces/batch \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "traces": [
      {
        "trace": {
          "trace_id": "550e8400-e29b-41d4-a716-446655440000",
          "agent": "lead-qualifier",
          "status": "completed",
          "started_at": "2024-01-15T10:00:00Z",
          "ended_at": "2024-01-15T10:00:02Z",
          "duration_ms": 2000,
          "success": true,
          "outcome": "qualified",
          "total_tokens": 1500,
          "total_cost_usd": "0.004500"
        },
        "spans": [
          {
            "span_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
            "trace_id": "550e8400-e29b-41d4-a716-446655440000",
            "type": "llm",
            "name": "gpt-4o classify",
            "status": "completed",
            "started_at": "2024-01-15T10:00:00.100Z",
            "ended_at": "2024-01-15T10:00:01.800Z",
            "duration_ms": 1700,
            "model": "gpt-4o",
            "input_tokens": 800,
            "output_tokens": 120,
            "total_tokens": 920,
            "cost_usd": "0.003200"
          }
        ]
      }
    ]
  }'

POST /traces/batch

Accepts a batch of traces and their spans from the SDK. Requires an API key with write scope.

The endpoint is idempotent: duplicate trace_id or span_id values are silently accepted. Agent records are auto-created on first trace for a new agent name.

The batch accepts up to 100 total spans across all traces in a single request. Exceeding your monthly event limit returns 429.

Request body

traces · object[] · required

Array of trace objects to ingest. Each object contains a trace header and its spans.

Show trace object

trace · object · required

Header-level fields for the trace.

Show trace fields

trace_id · string · required

SDK-generated UUID for this trace. Used for idempotent ingestion.

agent · string · required

Name of the agent that produced this trace. An Agent record is auto-created if this name is new.

status · string · default: "completed"

Trace status. One of running, completed, failed, timed_out.

started_at · string · required

ISO 8601 timestamp when the trace started.

ended_at · string

ISO 8601 timestamp when the trace ended. Null for in-progress traces.

duration_ms · number

Total duration in milliseconds.

success · boolean

Whether the agent run succeeded. Used for success rate calculations.

outcome · string

Free-text description of the outcome (e.g. "qualified", "rejected").

error_message · string

Error description if the trace failed.

total_tokens · number

Total tokens consumed across all LLM spans in this trace.

total_cost_usd · string

Total LLM cost in USD as a decimal string (e.g. "0.004500").

metadata · object

Arbitrary key-value metadata attached to this trace.

sdk_version · string · default: "0.2.0"

Version of the AgentVista SDK that produced this trace.

spans · object[] · required

Array of span objects within this trace.

Show span fields

span_id · string · required

SDK-generated UUID for this span.

trace_id · string · required

UUID of the parent trace.

parent_span_id · string

UUID of the parent span. Null for root spans.

type · string · required

Span type. One of agent, llm, tool, http, db, custom.

name · string · required

Human-readable name for this span (e.g. "gpt-4o classify").

status · string · default: "completed"

Span status. One of running, completed, failed, timed_out.

started_at · string · required

ISO 8601 timestamp when the span started.

ended_at · string

ISO 8601 timestamp when the span ended.

duration_ms · number

Span duration in milliseconds.

model · string

LLM model name (e.g. "gpt-4o"). Only relevant for llm spans.

input_tokens · number

Input token count. Only relevant for llm spans.

output_tokens · number

Output token count. Only relevant for llm spans.

total_tokens · number

Total token count for this span. Only relevant for llm spans.

cost_usd · string

LLM cost in USD for this span as a decimal string.

input_data · object

Input payload. For llm spans: the prompt. For http spans: the request.

output_data · object

Output payload. For llm spans: the completion. For http spans: the response.

error_message · string

Error description if this span failed.

metadata · object

Arbitrary key-value metadata.

Response — 200

accepted · number

Number of traces successfully ingested.

rejected · number

Number of traces that failed validation or ingestion.

errors · object[]

Per-trace error details for any rejected traces.

Show error object

trace_id · string

The trace_id of the rejected trace.

error · string

Description of why the trace was rejected.

Example response

{
  "accepted": 1,
  "rejected": 0,
  "errors": []
}

---

Get trace detail

cURL

curl https://api.agentvista.dev/api/v1/dashboard/traces/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET /dashboard/traces/{trace_id}

Returns a single trace with all its spans ordered by started_at ascending for waterfall rendering. Returns 404 for traces not owned by the authenticated user.

Path parameters

trace_id · string · required

The trace_id UUID of the trace to retrieve.

Response — 200

trace_id · string

The trace UUID.

agent_name · string

Name of the agent that produced this trace.

status · string

Trace status: running, completed, failed, or timed_out.

started_at · string

ISO 8601 timestamp.

ended_at · string | null

ISO 8601 timestamp or null.

duration_ms · number | null

Total duration in milliseconds.

success · boolean | null

Outcome signal. Null if not yet set.

outcome · string | null

Free-text outcome description.

error_message · string | null

Error description if the trace failed.

total_tokens · number | null

Total tokens consumed across all LLM spans.

total_cost_usd · number | null

Total LLM cost in USD.

metadata · object | null

Arbitrary metadata attached at ingestion time.

spans · object[]

All spans ordered by started_at ASC. Use parent_span_id to build the waterfall tree.

Show span fields

span_id · string

UUID of the span.

trace_id · string

UUID of the parent trace.

parent_span_id · string | null

UUID of the parent span, or null for root spans.

type · string

Span type: agent, llm, tool, http, db, or custom.

name · string

Human-readable span name.

status · string

Span status.

started_at · string

ISO 8601 timestamp.

ended_at · string | null

ISO 8601 timestamp or null.

duration_ms · number | null

Duration in milliseconds.

model · string | null

LLM model name, if applicable.

input_tokens · number | null

Input token count, if applicable.

output_tokens · number | null

Output token count, if applicable.

total_tokens · number | null

Total token count, if applicable.

cost_usd · number | null

LLM cost in USD for this span.

error_message · string | null

Error description.

input_data · object | null

Input payload.

output_data · object | null

Output payload.

---

Compare two agents

cURL

curl "https://api.agentvista.dev/api/v1/dashboard/traces/compare-agents?agent_a=UUID_A&agent_b=UUID_B" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET /dashboard/traces/compare-agents

Returns side-by-side aggregated stats for two agents. Both agents must belong to the authenticated user, otherwise 404 is returned.

Query parameters

agent_a · string · required

UUID of the first agent to compare.

agent_b · string · required

UUID of the second agent to compare.

Response — 200

agents · object[]

Array of exactly two agent stat objects, one per requested agent.

Show agent stat fields

id · string

Agent UUID.

name · string

Agent name.

total_runs · number

Total number of traces for this agent.

success_rate · number | null

Fraction of traces with success: true (e.g. 0.73 = 73%).

avg_cost_per_run · number | null

Average total_cost_usd per trace in USD.

total_cost · number | null

Sum of total_cost_usd across all traces.

p95_latency_ms · number | null

95th-percentile duration_ms across all traces.

last_run_at · string | null

ISO 8601 timestamp of the most recent trace.

---

Set trace outcome

cURL

curl -X PATCH https://api.agentvista.dev/api/v1/dashboard/traces/550e8400-e29b-41d4-a716-446655440000/outcome \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"success": true, "outcome": "qualified"}'

PATCH /dashboard/traces/{trace_id}/outcome

Sets the success and outcome fields on a trace. Use this to attach human or programmatic feedback to a completed trace. Returns 404 for traces not owned by the authenticated user.

Path parameters

trace_id · string · required

UUID of the trace to update.

Request body

success · boolean · required

Whether this trace is considered a success.

outcome · string

Free-text description of the outcome (e.g. "qualified", "rejected", "escalated").

Response — 200

trace_id · string

UUID of the updated trace.

success · boolean

The updated success value.

outcome · string | null

The updated outcome value.