616 lines
31 KiB
TypeScript
616 lines
31 KiB
TypeScript
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 (
|
|
<div className="mb-6">
|
|
<div className="flex items-center gap-3 mb-2">
|
|
<span
|
|
className={`px-2.5 py-1 rounded text-xs font-mono font-bold border ${methodColor}`}
|
|
>
|
|
{method}
|
|
</span>
|
|
<code className="text-lg font-mono text-neutral-200">{path}</code>
|
|
</div>
|
|
<p className="text-neutral-400">{description}</p>
|
|
</div>
|
|
);
|
|
}
|
|
|
|
export default function ApiReferencePage() {
|
|
return (
|
|
<div>
|
|
<h1 className="text-4xl font-bold tracking-tight mb-4">
|
|
REST API Reference
|
|
</h1>
|
|
<p className="text-lg text-neutral-400 mb-4 leading-relaxed">
|
|
The AgentLens REST API is used by the SDKs to ingest and retrieve
|
|
traces. You can also call it directly for custom integrations.
|
|
</p>
|
|
<div className="px-4 py-3 rounded-lg bg-neutral-900/50 border border-neutral-800/50 mb-10">
|
|
<span className="text-sm text-neutral-400">Base URL: </span>
|
|
<code className="text-sm font-mono text-emerald-400">
|
|
https://agentlens.vectry.tech
|
|
</code>
|
|
</div>
|
|
|
|
<section className="mb-6">
|
|
<h2 className="text-2xl font-semibold mb-4">Authentication</h2>
|
|
<p className="text-neutral-400 leading-relaxed mb-4">
|
|
All write endpoints require a Bearer token in the Authorization header:
|
|
</p>
|
|
<CodeBlock>{`Authorization: Bearer your-api-key`}</CodeBlock>
|
|
</section>
|
|
|
|
<hr className="border-neutral-800/50 my-10" />
|
|
|
|
<section className="mb-12">
|
|
<EndpointHeader
|
|
method="POST"
|
|
path="/api/traces"
|
|
description="Batch ingest one or more traces with their spans, decision points, and events."
|
|
/>
|
|
|
|
<h3 className="text-lg font-medium text-neutral-200 mb-3">
|
|
Request body
|
|
</h3>
|
|
<CodeBlock title="request_body.json" language="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": [ ... ]
|
|
}
|
|
]
|
|
}`}</CodeBlock>
|
|
|
|
<h3 className="text-lg font-medium text-neutral-200 mb-3 mt-8">
|
|
TracePayload
|
|
</h3>
|
|
<div className="overflow-x-auto">
|
|
<table className="w-full text-sm">
|
|
<thead>
|
|
<tr className="border-b border-neutral-800">
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Field</th>
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Type</th>
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Required</th>
|
|
<th className="text-left py-2 text-neutral-400 font-medium">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody className="text-neutral-300">
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">id</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">UUID v4 unique identifier</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">name</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">Human-readable trace name</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">sessionId</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Group traces into a session</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">status</td>
|
|
<td className="py-2 pr-4 text-neutral-500">enum</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">RUNNING | COMPLETED | ERROR</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">tags</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string[]</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">Array of tag strings</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">metadata</td>
|
|
<td className="py-2 pr-4 text-neutral-500">object</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Arbitrary JSON metadata</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">totalCost</td>
|
|
<td className="py-2 pr-4 text-neutral-500">number</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Total cost in USD</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">totalTokens</td>
|
|
<td className="py-2 pr-4 text-neutral-500">number</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Total token count</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">totalDuration</td>
|
|
<td className="py-2 pr-4 text-neutral-500">number</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Total duration in milliseconds</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">startedAt</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">ISO 8601 datetime</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">endedAt</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">ISO 8601 datetime (null if RUNNING)</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">spans</td>
|
|
<td className="py-2 pr-4 text-neutral-500">SpanPayload[]</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">Array of spans (can be empty)</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">decisionPoints</td>
|
|
<td className="py-2 pr-4 text-neutral-500">DecisionPointPayload[]</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">Array of decision points (can be empty)</td>
|
|
</tr>
|
|
<tr>
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">events</td>
|
|
<td className="py-2 pr-4 text-neutral-500">EventPayload[]</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">Array of events (can be empty)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<h3 className="text-lg font-medium text-neutral-200 mb-3 mt-8">
|
|
SpanPayload
|
|
</h3>
|
|
<div className="overflow-x-auto">
|
|
<table className="w-full text-sm">
|
|
<thead>
|
|
<tr className="border-b border-neutral-800">
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Field</th>
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Type</th>
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Required</th>
|
|
<th className="text-left py-2 text-neutral-400 font-medium">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody className="text-neutral-300">
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">id</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">UUID v4</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">parentSpanId</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Parent span ID for nesting</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">name</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">Span name</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">type</td>
|
|
<td className="py-2 pr-4 text-neutral-500">enum</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">LLM_CALL | TOOL_CALL | MEMORY_OP | CHAIN | AGENT | CUSTOM</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">input</td>
|
|
<td className="py-2 pr-4 text-neutral-500">object</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">JSON input payload</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">output</td>
|
|
<td className="py-2 pr-4 text-neutral-500">object</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">JSON output payload</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">tokenCount</td>
|
|
<td className="py-2 pr-4 text-neutral-500">number</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Total tokens</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">costUsd</td>
|
|
<td className="py-2 pr-4 text-neutral-500">number</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Cost in USD</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">durationMs</td>
|
|
<td className="py-2 pr-4 text-neutral-500">number</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Duration in milliseconds</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">status</td>
|
|
<td className="py-2 pr-4 text-neutral-500">enum</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">RUNNING | COMPLETED | ERROR</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">statusMessage</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Error message or status description</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">startedAt</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">ISO 8601 datetime</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">endedAt</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">ISO 8601 datetime</td>
|
|
</tr>
|
|
<tr>
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">metadata</td>
|
|
<td className="py-2 pr-4 text-neutral-500">object</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Arbitrary JSON metadata</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<h3 className="text-lg font-medium text-neutral-200 mb-3 mt-8">
|
|
DecisionPointPayload
|
|
</h3>
|
|
<div className="overflow-x-auto">
|
|
<table className="w-full text-sm">
|
|
<thead>
|
|
<tr className="border-b border-neutral-800">
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Field</th>
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Type</th>
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Required</th>
|
|
<th className="text-left py-2 text-neutral-400 font-medium">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody className="text-neutral-300">
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">id</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">UUID v4</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">type</td>
|
|
<td className="py-2 pr-4 text-neutral-500">enum</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">TOOL_SELECTION | ROUTING | RETRY | ESCALATION | MEMORY_RETRIEVAL | PLANNING | CUSTOM</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">reasoning</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Why this choice was made</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">chosen</td>
|
|
<td className="py-2 pr-4 text-neutral-500">object</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">JSON value representing the choice made</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">alternatives</td>
|
|
<td className="py-2 pr-4 text-neutral-500">object[]</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">Array of alternatives considered</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">contextSnapshot</td>
|
|
<td className="py-2 pr-4 text-neutral-500">object</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Context at decision time</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">durationMs</td>
|
|
<td className="py-2 pr-4 text-neutral-500">number</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Decision time in milliseconds</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">costUsd</td>
|
|
<td className="py-2 pr-4 text-neutral-500">number</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Cost of this decision</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">parentSpanId</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Span this decision belongs to</td>
|
|
</tr>
|
|
<tr>
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">timestamp</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">ISO 8601 datetime</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<h3 className="text-lg font-medium text-neutral-200 mb-3 mt-8">
|
|
EventPayload
|
|
</h3>
|
|
<div className="overflow-x-auto">
|
|
<table className="w-full text-sm">
|
|
<thead>
|
|
<tr className="border-b border-neutral-800">
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Field</th>
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Type</th>
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Required</th>
|
|
<th className="text-left py-2 text-neutral-400 font-medium">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody className="text-neutral-300">
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">id</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">UUID v4</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">spanId</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Span this event is associated with</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">type</td>
|
|
<td className="py-2 pr-4 text-neutral-500">enum</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">ERROR | RETRY | FALLBACK | CONTEXT_OVERFLOW | USER_FEEDBACK | CUSTOM</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">name</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">Human-readable event name</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">metadata</td>
|
|
<td className="py-2 pr-4 text-neutral-500">object</td>
|
|
<td className="py-2 pr-4 text-neutral-500">No</td>
|
|
<td className="py-2">Arbitrary JSON metadata</td>
|
|
</tr>
|
|
<tr>
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">timestamp</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">Yes</td>
|
|
<td className="py-2">ISO 8601 datetime</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<h3 className="text-lg font-medium text-neutral-200 mb-3 mt-8">
|
|
Responses
|
|
</h3>
|
|
<div className="space-y-3">
|
|
<div className="p-3 rounded-lg border border-neutral-800/50 bg-neutral-900/30 flex items-start gap-3">
|
|
<span className="px-2 py-0.5 rounded text-xs font-mono font-bold bg-emerald-500/10 text-emerald-400 border border-emerald-500/20 flex-shrink-0">
|
|
200
|
|
</span>
|
|
<div>
|
|
<p className="text-sm text-neutral-300">Success</p>
|
|
<code className="text-xs font-mono text-neutral-500">{`{ "success": true, "count": 1 }`}</code>
|
|
</div>
|
|
</div>
|
|
<div className="p-3 rounded-lg border border-neutral-800/50 bg-neutral-900/30 flex items-start gap-3">
|
|
<span className="px-2 py-0.5 rounded text-xs font-mono font-bold bg-amber-500/10 text-amber-400 border border-amber-500/20 flex-shrink-0">
|
|
400
|
|
</span>
|
|
<div>
|
|
<p className="text-sm text-neutral-300">Bad Request</p>
|
|
<code className="text-xs font-mono text-neutral-500">{`{ "error": "Request body must contain a 'traces' array" }`}</code>
|
|
</div>
|
|
</div>
|
|
<div className="p-3 rounded-lg border border-neutral-800/50 bg-neutral-900/30 flex items-start gap-3">
|
|
<span className="px-2 py-0.5 rounded text-xs font-mono font-bold bg-red-500/10 text-red-400 border border-red-500/20 flex-shrink-0">
|
|
401
|
|
</span>
|
|
<div>
|
|
<p className="text-sm text-neutral-300">Unauthorized</p>
|
|
<code className="text-xs font-mono text-neutral-500">{`{ "error": "Missing or invalid Authorization header" }`}</code>
|
|
</div>
|
|
</div>
|
|
<div className="p-3 rounded-lg border border-neutral-800/50 bg-neutral-900/30 flex items-start gap-3">
|
|
<span className="px-2 py-0.5 rounded text-xs font-mono font-bold bg-amber-500/10 text-amber-400 border border-amber-500/20 flex-shrink-0">
|
|
409
|
|
</span>
|
|
<div>
|
|
<p className="text-sm text-neutral-300">Conflict</p>
|
|
<code className="text-xs font-mono text-neutral-500">{`{ "error": "Duplicate trace ID detected" }`}</code>
|
|
</div>
|
|
</div>
|
|
<div className="p-3 rounded-lg border border-neutral-800/50 bg-neutral-900/30 flex items-start gap-3">
|
|
<span className="px-2 py-0.5 rounded text-xs font-mono font-bold bg-red-500/10 text-red-400 border border-red-500/20 flex-shrink-0">
|
|
500
|
|
</span>
|
|
<div>
|
|
<p className="text-sm text-neutral-300">Internal Server Error</p>
|
|
<code className="text-xs font-mono text-neutral-500">{`{ "error": "Internal server error" }`}</code>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<h3 className="text-lg font-medium text-neutral-200 mb-3 mt-8">
|
|
cURL example
|
|
</h3>
|
|
<CodeBlock title="terminal" language="bash">{`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": []
|
|
}]
|
|
}'`}</CodeBlock>
|
|
</section>
|
|
|
|
<hr className="border-neutral-800/50 my-10" />
|
|
|
|
<section>
|
|
<EndpointHeader
|
|
method="GET"
|
|
path="/api/traces"
|
|
description="List traces with pagination, filtering, and sorting."
|
|
/>
|
|
|
|
<h3 className="text-lg font-medium text-neutral-200 mb-3">
|
|
Query parameters
|
|
</h3>
|
|
<div className="overflow-x-auto">
|
|
<table className="w-full text-sm">
|
|
<thead>
|
|
<tr className="border-b border-neutral-800">
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Param</th>
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Type</th>
|
|
<th className="text-left py-2 pr-4 text-neutral-400 font-medium">Default</th>
|
|
<th className="text-left py-2 text-neutral-400 font-medium">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody className="text-neutral-300">
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">page</td>
|
|
<td className="py-2 pr-4 text-neutral-500">integer</td>
|
|
<td className="py-2 pr-4 text-neutral-500">1</td>
|
|
<td className="py-2">Page number (1-based)</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">limit</td>
|
|
<td className="py-2 pr-4 text-neutral-500">integer</td>
|
|
<td className="py-2 pr-4 text-neutral-500">20</td>
|
|
<td className="py-2">Results per page (1-100)</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">status</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">-</td>
|
|
<td className="py-2">Filter by status: RUNNING, COMPLETED, ERROR</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">search</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">-</td>
|
|
<td className="py-2">Case-insensitive search on trace name</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">sessionId</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">-</td>
|
|
<td className="py-2">Filter by session ID</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">tags</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">-</td>
|
|
<td className="py-2">Comma-separated tags (matches any)</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">sort</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">newest</td>
|
|
<td className="py-2">newest, oldest, longest, shortest, costliest</td>
|
|
</tr>
|
|
<tr className="border-b border-neutral-800/50">
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">dateFrom</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">-</td>
|
|
<td className="py-2">ISO 8601 lower bound</td>
|
|
</tr>
|
|
<tr>
|
|
<td className="py-2 pr-4 font-mono text-emerald-400 text-xs">dateTo</td>
|
|
<td className="py-2 pr-4 text-neutral-500">string</td>
|
|
<td className="py-2 pr-4 text-neutral-500">-</td>
|
|
<td className="py-2">ISO 8601 upper bound</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<h3 className="text-lg font-medium text-neutral-200 mb-3 mt-8">
|
|
Response shape
|
|
</h3>
|
|
<CodeBlock title="response.json" language="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
|
|
}`}</CodeBlock>
|
|
</section>
|
|
</div>
|
|
);
|
|
}
|