import type { Metadata } from "next"; import { CodeBlock } from "@/components/code-block"; export const metadata: Metadata = { title: "REST API Reference", description: "Complete API contract for AgentLens trace ingestion and retrieval endpoints.", }; function EndpointHeader({ method, path, description, }: { method: string; path: string; description: string; }) { const methodColor = method === "POST" ? "bg-amber-500/10 text-amber-400 border-amber-500/20" : "bg-emerald-500/10 text-emerald-400 border-emerald-500/20"; return (
{method} {path}

{description}

); } export default function ApiReferencePage() { return (

REST API Reference

The AgentLens REST API is used by the SDKs to ingest and retrieve traces. You can also call it directly for custom integrations.

Base URL: https://agentlens.vectry.tech

Authentication

All write endpoints require a Bearer token in the Authorization header:

{`Authorization: Bearer your-api-key`}

Request body

{`{ "traces": [ { "id": "trace-uuid-v4", "name": "my-agent-run", "sessionId": "session-abc", "status": "COMPLETED", "tags": ["production", "v2"], "metadata": { "user_id": "u-123" }, "totalCost": 0.045, "totalTokens": 1500, "totalDuration": 3200, "startedAt": "2026-01-15T10:00:00.000Z", "endedAt": "2026-01-15T10:00:03.200Z", "spans": [ ... ], "decisionPoints": [ ... ], "events": [ ... ] } ] }`}

TracePayload

Field Type Required Description
id string Yes UUID v4 unique identifier
name string Yes Human-readable trace name
sessionId string No Group traces into a session
status enum Yes RUNNING | COMPLETED | ERROR
tags string[] Yes Array of tag strings
metadata object No Arbitrary JSON metadata
totalCost number No Total cost in USD
totalTokens number No Total token count
totalDuration number No Total duration in milliseconds
startedAt string Yes ISO 8601 datetime
endedAt string No ISO 8601 datetime (null if RUNNING)
spans SpanPayload[] Yes Array of spans (can be empty)
decisionPoints DecisionPointPayload[] Yes Array of decision points (can be empty)
events EventPayload[] Yes Array of events (can be empty)

SpanPayload

Field Type Required Description
id string Yes UUID v4
parentSpanId string No Parent span ID for nesting
name string Yes Span name
type enum Yes LLM_CALL | TOOL_CALL | MEMORY_OP | CHAIN | AGENT | CUSTOM
input object No JSON input payload
output object No JSON output payload
tokenCount number No Total tokens
costUsd number No Cost in USD
durationMs number No Duration in milliseconds
status enum Yes RUNNING | COMPLETED | ERROR
statusMessage string No Error message or status description
startedAt string Yes ISO 8601 datetime
endedAt string No ISO 8601 datetime
metadata object No Arbitrary JSON metadata

DecisionPointPayload

Field Type Required Description
id string Yes UUID v4
type enum Yes TOOL_SELECTION | ROUTING | RETRY | ESCALATION | MEMORY_RETRIEVAL | PLANNING | CUSTOM
reasoning string No Why this choice was made
chosen object Yes JSON value representing the choice made
alternatives object[] Yes Array of alternatives considered
contextSnapshot object No Context at decision time
durationMs number No Decision time in milliseconds
costUsd number No Cost of this decision
parentSpanId string No Span this decision belongs to
timestamp string Yes ISO 8601 datetime

EventPayload

Field Type Required Description
id string Yes UUID v4
spanId string No Span this event is associated with
type enum Yes ERROR | RETRY | FALLBACK | CONTEXT_OVERFLOW | USER_FEEDBACK | CUSTOM
name string Yes Human-readable event name
metadata object No Arbitrary JSON metadata
timestamp string Yes ISO 8601 datetime

Responses

200

Success

{`{ "success": true, "count": 1 }`}
400

Bad Request

{`{ "error": "Request body must contain a 'traces' array" }`}
401

Unauthorized

{`{ "error": "Missing or invalid Authorization header" }`}
409

Conflict

{`{ "error": "Duplicate trace ID detected" }`}
500

Internal Server Error

{`{ "error": "Internal server error" }`}

cURL example

{`curl -X POST https://agentlens.vectry.tech/api/traces \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer your-api-key" \\ -d '{ "traces": [{ "id": "550e8400-e29b-41d4-a716-446655440000", "name": "test-trace", "status": "COMPLETED", "tags": ["test"], "startedAt": "2026-01-15T10:00:00.000Z", "endedAt": "2026-01-15T10:00:01.000Z", "spans": [], "decisionPoints": [], "events": [] }] }'`}

Query parameters

Param Type Default Description
page integer 1 Page number (1-based)
limit integer 20 Results per page (1-100)
status string - Filter by status: RUNNING, COMPLETED, ERROR
search string - Case-insensitive search on trace name
sessionId string - Filter by session ID
tags string - Comma-separated tags (matches any)
sort string newest newest, oldest, longest, shortest, costliest
dateFrom string - ISO 8601 lower bound
dateTo string - ISO 8601 upper bound

Response shape

{`{ "traces": [ { "id": "...", "name": "my-agent", "status": "COMPLETED", "tags": ["production"], "startedAt": "2026-01-15T10:00:00.000Z", "endedAt": "2026-01-15T10:00:03.200Z", "totalCost": 0.045, "totalTokens": 1500, "totalDuration": 3200, "_count": { "decisionPoints": 3, "spans": 7, "events": 1 } } ], "total": 142, "page": 1, "limit": 20, "totalPages": 8 }`}
); }