> ## Documentation Index
> Fetch the complete documentation index at: https://moonshotfactory.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```bash cURL theme={null}
  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"
            }
          ]
        }
      ]
    }'
  ```
</CodeGroup>

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

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

### Request body

<ParamField body="traces" type="object[]" required>
  Array of trace objects to ingest. Each object contains a trace header and its spans.

  <Expandable title="trace object">
    <ParamField body="trace" type="object" required>
      Header-level fields for the trace.

      <Expandable title="trace fields">
        <ParamField body="trace_id" type="string" required>
          SDK-generated UUID for this trace. Used for idempotent ingestion.
        </ParamField>

        <ParamField body="agent" type="string" required>
          Name of the agent that produced this trace. An Agent record is auto-created if this name is new.
        </ParamField>

        <ParamField body="status" type="string" default="completed">
          Trace status. One of `running`, `completed`, `failed`, `timed_out`.
        </ParamField>

        <ParamField body="started_at" type="string" required>
          ISO 8601 timestamp when the trace started.
        </ParamField>

        <ParamField body="ended_at" type="string">
          ISO 8601 timestamp when the trace ended. Null for in-progress traces.
        </ParamField>

        <ParamField body="duration_ms" type="number">
          Total duration in milliseconds.
        </ParamField>

        <ParamField body="success" type="boolean">
          Whether the agent run succeeded. Used for success rate calculations.
        </ParamField>

        <ParamField body="outcome" type="string">
          Free-text description of the outcome (e.g. `"qualified"`, `"rejected"`).
        </ParamField>

        <ParamField body="error_message" type="string">
          Error description if the trace failed.
        </ParamField>

        <ParamField body="total_tokens" type="number">
          Total tokens consumed across all LLM spans in this trace.
        </ParamField>

        <ParamField body="total_cost_usd" type="string">
          Total LLM cost in USD as a decimal string (e.g. `"0.004500"`).
        </ParamField>

        <ParamField body="metadata" type="object">
          Arbitrary key-value metadata attached to this trace.
        </ParamField>

        <ParamField body="sdk_version" type="string" default="0.2.0">
          Version of the AgentVista SDK that produced this trace.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="spans" type="object[]" required>
      Array of span objects within this trace.

      <Expandable title="span fields">
        <ParamField body="span_id" type="string" required>
          SDK-generated UUID for this span.
        </ParamField>

        <ParamField body="trace_id" type="string" required>
          UUID of the parent trace.
        </ParamField>

        <ParamField body="parent_span_id" type="string">
          UUID of the parent span. Null for root spans.
        </ParamField>

        <ParamField body="type" type="string" required>
          Span type. One of `agent`, `llm`, `tool`, `http`, `db`, `custom`.
        </ParamField>

        <ParamField body="name" type="string" required>
          Human-readable name for this span (e.g. `"gpt-4o classify"`).
        </ParamField>

        <ParamField body="status" type="string" default="completed">
          Span status. One of `running`, `completed`, `failed`, `timed_out`.
        </ParamField>

        <ParamField body="started_at" type="string" required>
          ISO 8601 timestamp when the span started.
        </ParamField>

        <ParamField body="ended_at" type="string">
          ISO 8601 timestamp when the span ended.
        </ParamField>

        <ParamField body="duration_ms" type="number">
          Span duration in milliseconds.
        </ParamField>

        <ParamField body="model" type="string">
          LLM model name (e.g. `"gpt-4o"`). Only relevant for `llm` spans.
        </ParamField>

        <ParamField body="input_tokens" type="number">
          Input token count. Only relevant for `llm` spans.
        </ParamField>

        <ParamField body="output_tokens" type="number">
          Output token count. Only relevant for `llm` spans.
        </ParamField>

        <ParamField body="total_tokens" type="number">
          Total token count for this span. Only relevant for `llm` spans.
        </ParamField>

        <ParamField body="cost_usd" type="string">
          LLM cost in USD for this span as a decimal string.
        </ParamField>

        <ParamField body="input_data" type="object">
          Input payload. For `llm` spans: the prompt. For `http` spans: the request.
        </ParamField>

        <ParamField body="output_data" type="object">
          Output payload. For `llm` spans: the completion. For `http` spans: the response.
        </ParamField>

        <ParamField body="error_message" type="string">
          Error description if this span failed.
        </ParamField>

        <ParamField body="metadata" type="object">
          Arbitrary key-value metadata.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response — 200

<ResponseField name="accepted" type="number">
  Number of traces successfully ingested.
</ResponseField>

<ResponseField name="rejected" type="number">
  Number of traces that failed validation or ingestion.
</ResponseField>

<ResponseField name="errors" type="object[]">
  Per-trace error details for any rejected traces.

  <Expandable title="error object">
    <ResponseField name="trace_id" type="string">
      The `trace_id` of the rejected trace.
    </ResponseField>

    <ResponseField name="error" type="string">
      Description of why the trace was rejected.
    </ResponseField>
  </Expandable>
</ResponseField>

```json Example response theme={null}
{
  "accepted": 1,
  "rejected": 0,
  "errors": []
}
```

***

## Get trace detail

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/dashboard/traces/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`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

<ParamField path="trace_id" type="string" required>
  The `trace_id` UUID of the trace to retrieve.
</ParamField>

### Response — 200

<ResponseField name="trace_id" type="string">
  The trace UUID.
</ResponseField>

<ResponseField name="agent_name" type="string">
  Name of the agent that produced this trace.
</ResponseField>

<ResponseField name="status" type="string">
  Trace status: `running`, `completed`, `failed`, or `timed_out`.
</ResponseField>

<ResponseField name="started_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="ended_at" type="string | null">
  ISO 8601 timestamp or null.
</ResponseField>

<ResponseField name="duration_ms" type="number | null">
  Total duration in milliseconds.
</ResponseField>

<ResponseField name="success" type="boolean | null">
  Outcome signal. Null if not yet set.
</ResponseField>

<ResponseField name="outcome" type="string | null">
  Free-text outcome description.
</ResponseField>

<ResponseField name="error_message" type="string | null">
  Error description if the trace failed.
</ResponseField>

<ResponseField name="total_tokens" type="number | null">
  Total tokens consumed across all LLM spans.
</ResponseField>

<ResponseField name="total_cost_usd" type="number | null">
  Total LLM cost in USD.
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Arbitrary metadata attached at ingestion time.
</ResponseField>

<ResponseField name="spans" type="object[]">
  All spans ordered by `started_at` ASC. Use `parent_span_id` to build the waterfall tree.

  <Expandable title="span fields">
    <ResponseField name="span_id" type="string">UUID of the span.</ResponseField>
    <ResponseField name="trace_id" type="string">UUID of the parent trace.</ResponseField>
    <ResponseField name="parent_span_id" type="string | null">UUID of the parent span, or null for root spans.</ResponseField>
    <ResponseField name="type" type="string">Span type: `agent`, `llm`, `tool`, `http`, `db`, or `custom`.</ResponseField>
    <ResponseField name="name" type="string">Human-readable span name.</ResponseField>
    <ResponseField name="status" type="string">Span status.</ResponseField>
    <ResponseField name="started_at" type="string">ISO 8601 timestamp.</ResponseField>
    <ResponseField name="ended_at" type="string | null">ISO 8601 timestamp or null.</ResponseField>
    <ResponseField name="duration_ms" type="number | null">Duration in milliseconds.</ResponseField>
    <ResponseField name="model" type="string | null">LLM model name, if applicable.</ResponseField>
    <ResponseField name="input_tokens" type="number | null">Input token count, if applicable.</ResponseField>
    <ResponseField name="output_tokens" type="number | null">Output token count, if applicable.</ResponseField>
    <ResponseField name="total_tokens" type="number | null">Total token count, if applicable.</ResponseField>
    <ResponseField name="cost_usd" type="number | null">LLM cost in USD for this span.</ResponseField>
    <ResponseField name="error_message" type="string | null">Error description.</ResponseField>
    <ResponseField name="input_data" type="object | null">Input payload.</ResponseField>
    <ResponseField name="output_data" type="object | null">Output payload.</ResponseField>
  </Expandable>
</ResponseField>

***

## Compare two agents

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.agentvista.dev/api/v1/dashboard/traces/compare-agents?agent_a=UUID_A&agent_b=UUID_B" \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`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

<ParamField query="agent_a" type="string" required>
  UUID of the first agent to compare.
</ParamField>

<ParamField query="agent_b" type="string" required>
  UUID of the second agent to compare.
</ParamField>

### Response — 200

<ResponseField name="agents" type="object[]">
  Array of exactly two agent stat objects, one per requested agent.

  <Expandable title="agent stat fields">
    <ResponseField name="id" type="string">Agent UUID.</ResponseField>
    <ResponseField name="name" type="string">Agent name.</ResponseField>
    <ResponseField name="total_runs" type="number">Total number of traces for this agent.</ResponseField>
    <ResponseField name="success_rate" type="number | null">Fraction of traces with `success: true` (e.g. `0.73` = 73%).</ResponseField>
    <ResponseField name="avg_cost_per_run" type="number | null">Average `total_cost_usd` per trace in USD.</ResponseField>
    <ResponseField name="total_cost" type="number | null">Sum of `total_cost_usd` across all traces.</ResponseField>
    <ResponseField name="p95_latency_ms" type="number | null">95th-percentile `duration_ms` across all traces.</ResponseField>
    <ResponseField name="last_run_at" type="string | null">ISO 8601 timestamp of the most recent trace.</ResponseField>
  </Expandable>
</ResponseField>

***

## Set trace outcome

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```
</CodeGroup>

`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

<ParamField path="trace_id" type="string" required>
  UUID of the trace to update.
</ParamField>

### Request body

<ParamField body="success" type="boolean" required>
  Whether this trace is considered a success.
</ParamField>

<ParamField body="outcome" type="string">
  Free-text description of the outcome (e.g. `"qualified"`, `"rejected"`, `"escalated"`).
</ParamField>

### Response — 200

<ResponseField name="trace_id" type="string">
  UUID of the updated trace.
</ResponseField>

<ResponseField name="success" type="boolean">
  The updated success value.
</ResponseField>

<ResponseField name="outcome" type="string | null">
  The updated outcome value.
</ResponseField>