Introduction

curl -s -X POST https://tracing.art3m1s.me/api/v1/traces \
  -H "Authorization: Bearer $FIRETRACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaVersion": 1,
    "trace": {
      "id": "42f38ac8295345a7a12c4e3f60d6da23",
      "name": "answer-question",
      "status": "ok",
      "startedAt": "2026-09-02T19:01:02.120Z",
      "endedAt": "2026-09-02T19:01:04.812Z",
      "model": "example-model",
      "input": {
        "prompt": "Explain vector search in two sentences."
      },
      "output": {
        "text": "Vector search finds items whose embeddings are nearest to a query embedding."
      },
      "usage": {
        "inputTokens": 412,
        "outputTokens": 96,
        "totalTokens": 508
      },
      "tags": [],
      "metadata": {},
      "spans": [
        {
          "id": "00f067aa0ba902b7",
          "parentSpanId": null,
          "name": "generate-text",
          "kind": "llm",
          "status": "ok",
          "startedAt": "2026-09-02T19:01:02.145Z",
          "endedAt": "2026-09-02T19:01:04.780Z",
          "model": "example-model",
          "attributes": {},
          "events": [],
          "usage": {}
        }
      ]
    }
  }'

import { FireTrace } from "@firetrace/sdk";

const client = new FireTrace({
  endpoint: process.env.FIRETRACE_ENDPOINT!, // "https://tracing.art3m1s.me"
  apiKey: process.env.FIRETRACE_API_KEY!, // "ft_live_<keyId>_<secret>"
  onError: (err) => console.warn("firetrace:", err.code, err.message),
});

const trace = client.startTrace("answer-question", {
  model: "example-model",
  input: { prompt },
});
const llm = trace.startSpan("generate-text", { kind: "llm", model: "example-model" });

const result = await callModel();
llm.end({ status: "ok", output: { text: result.text }, usage: result.usage });

const sent = await trace.end({ status: "ok", output: { text: result.text } });
if (sent.ok) console.log(sent.response.traceId, sent.response.duplicate);

const body = {
  schemaVersion: 1,
  trace: {
    id: crypto.randomUUID().replaceAll("-", ""), // 32 hex characters
    name: "answer-question",
    status: "ok",
    startedAt: startedAt.toISOString(),
    endedAt: new Date().toISOString(),
    model: "example-model",
    input: { prompt },
    output: { text },
    spans: [],
  },
};

const res = await fetch("https://tracing.art3m1s.me/api/v1/traces", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FIRETRACE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
if (!res.ok) console.warn("firetrace:", res.status, await res.text());

const trace = client.startTrace("answer-question", { input: { prompt } });

const agent = trace.startSpan("answer-question", { kind: "agent" });
agent.addEvent("plan.ready", { steps: 2 });

const tool = agent.startSpan("lookup", { kind: "tool", input: { url } });
tool.end({ status: "ok", output: { status: 200 } });

const llm = agent.startSpan("generate-text", {
  kind: "llm",
  provider: "example-provider",
  model: "example-model",
  input: { messages },
});
llm.end({ status: "ok", output: { text }, usage, costUsd });

agent.end({ status: "ok" });
await trace.end({ status: "ok", output: { text }, usage });

{
  "id": "b7ad6b7169203331",
  "parentSpanId": "00f067aa0ba902b7",
  "name": "lookup-example",
  "kind": "tool",
  "status": "error",
  "startedAt": "2026-09-02T19:01:03.050Z",
  "endedAt": "2026-09-02T19:01:03.600Z",
  "input": {
    "tool": "docs.fetch",
    "url": "https://example.com/vector-search"
  },
  "attributes": {
    "error.type": "HttpError",
    "error.message": "HTTP 429 Too Many Requests after 2 retries"
  },
  "events": [
    {
      "name": "retry",
      "timestamp": "2026-09-02T19:01:03.220Z",
      "attributes": {
        "attempt": 1
      }
    },
    {
      "name": "retry",
      "timestamp": "2026-09-02T19:01:03.420Z",
      "attributes": {
        "attempt": 2
      }
    }
  ],
  "usage": {}
}

curl -s "https://tracing.art3m1s.me/api/v1/traces?status=error&limit=5" \
  -H "Authorization: Bearer $FIRETRACE_API_KEY"

import { FireTraceApi } from "@firetrace/sdk";

const api = new FireTraceApi({
  endpoint: "https://tracing.art3m1s.me",
  apiKey: process.env.FIRETRACE_API_KEY!,
});

const page = await api.listTraces({ status: "error", limit: 20 });
const detail = await api.getTrace(page.traces[0].id); // trace, spans and scores
for await (const trace of api.iterateTraces({ model: "example-model" })) console.log(trace.id);

Using the firetrace MCP server, list the last 10 error traces in this
project. For the slowest one, find the failing span with find_spans, read
the surrounding input and output with get_trace, and tell me what broke.
Then record your verdict on that trace with add_score.

curl -s -X POST https://tracing.art3m1s.me/api/v1/traces/$TRACE_ID/scores \
  -H "Authorization: Bearer $FIRETRACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"helpful","dataType":"boolean","value":true,"comment":"answered the question"}'

await api.addScore(traceId, {
  name: "helpful",
  dataType: "boolean",
  value: true,
  comment: "answered the question",
});

// Every "helpful" score across the project, newest first.
const helpful = await api.listScores({ name: "helpful", limit: 100 });