Traces

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

object[]

required

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

Show trace object

object

required

Header-level fields for the trace.

Show trace fields

string

required

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

string

required

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

string

default:"completed"

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

string

required

ISO 8601 timestamp when the trace started.

string

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

number

Total duration in milliseconds.

boolean

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

string

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

string

Error description if the trace failed.

number

Total tokens consumed across all LLM spans in this trace.

string

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

object

Arbitrary key-value metadata attached to this trace.

string

default:"0.2.0"

Version of the AgentVista SDK that produced this trace.

object[]

required

Array of span objects within this trace.

Show span fields

string

required

SDK-generated UUID for this span.

string

required

UUID of the parent trace.

string

UUID of the parent span. Null for root spans.

string

required

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

string

required

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

string

default:"completed"

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

string

required

ISO 8601 timestamp when the span started.

string

ISO 8601 timestamp when the span ended.

number

Span duration in milliseconds.

string

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

number

Input token count. Only relevant for llm spans.

number

Output token count. Only relevant for llm spans.

number

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

string

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

object

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

object

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

string

Error description if this span failed.

object

Arbitrary key-value metadata.

Response — 200

number

Number of traces successfully ingested.

number

Number of traces that failed validation or ingestion.

object[]

Per-trace error details for any rejected traces.

Show error object

string

The trace_id of the rejected trace.

string

Description of why the trace was rejected.

Example response

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

Get trace detail

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

string

required

The trace_id UUID of the trace to retrieve.

Response — 200

string

The trace UUID.

string

Name of the agent that produced this trace.

string

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

string

ISO 8601 timestamp.

string | null

ISO 8601 timestamp or null.

number | null

Total duration in milliseconds.

boolean | null

Outcome signal. Null if not yet set.

string | null

Free-text outcome description.

string | null

Error description if the trace failed.

number | null

Total tokens consumed across all LLM spans.

number | null

Total LLM cost in USD.

object | null

Arbitrary metadata attached at ingestion time.

object[]

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

Show span fields

string

UUID of the span.

string

UUID of the parent trace.

string | null

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

string

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

string

Human-readable span name.

string

Span status.

string

ISO 8601 timestamp.

string | null

ISO 8601 timestamp or null.

number | null

Duration in milliseconds.

string | null

LLM model name, if applicable.

number | null

Input token count, if applicable.

number | null

Output token count, if applicable.

number | null

Total token count, if applicable.

number | null

LLM cost in USD for this span.

string | null

Error description.

object | null

Input payload.

object | null

Output payload.

Compare two agents

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

string

required

UUID of the first agent to compare.

string

required

UUID of the second agent to compare.

Response — 200

object[]

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

Show agent stat fields

string

Agent UUID.

string

Agent name.

number

Total number of traces for this agent.

number | null

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

number | null

Average total_cost_usd per trace in USD.

number | null

Sum of total_cost_usd across all traces.

number | null

95th-percentile duration_ms across all traces.

string | null

ISO 8601 timestamp of the most recent trace.

Set trace outcome

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

string

required

UUID of the trace to update.

Request body

boolean

required

Whether this trace is considered a success.

string

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

Response — 200

string

UUID of the updated trace.

boolean

The updated success value.

string | null

The updated outcome value.

Overview

Ingestion

Dashboard

Ingest a batch of traces

Request body

Response — 200

Get trace detail

Path parameters

Response — 200

Compare two agents

Query parameters

Response — 200

Set trace outcome

Path parameters

Request body

Response — 200

​Ingest a batch of traces

​Request body

​Response — 200

​Get trace detail

​Path parameters

​Response — 200

​Compare two agents

​Query parameters

​Response — 200

​Set trace outcome

​Path parameters

​Request body

​Response — 200

Ingest a batch of traces

Request body

Response — 200

Get trace detail

Path parameters

Response — 200

Compare two agents

Query parameters

Response — 200

Set trace outcome

Path parameters

Request body

Response — 200