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

POST/api/traces

Batch ingest one or more traces with their spans, decision points, and events.

Request body

request_body.json

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

terminal

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": []
    }]
  }'

GET/api/traces

List traces with pagination, filtering, and sorting.

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

response.json

{
  "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
}