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>
  );
}
