HTTP Trace Injection

curl -X POST https://ingest.neatlogs.com/v1/trace \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-write-key>" \
  -d '{
    "name": "my-workflow",
    "project": "my-project",
    "children": [
      {
        "name": "answer",
        "kind": "LLM",
        "model": "gpt-4o",
        "input": "What is the capital of France?",
        "output": "Paris.",
        "tokens": { "prompt": 12, "completion": 3 }
      }
    ]
  }'

x-api-key: <your-write-key>

Authorization: Bearer <your-write-key>

{
  "name": "string (required) — root name becomes the workflow name",
  "project": "string (root only, required with a write key) — target project NAME",
  "kind": "string (optional) — span kind; inferred from the fields when omitted",
  "input": "any (optional) — step input",
  "output": "any (optional) — step output",
  "model": "string (optional) — LLM model name",
  "tokens": { "prompt": 0, "completion": 0, "total": 0 },
  "query": "any (optional) — retriever / reranker query",
  "documents": "any (optional) — retriever / reranker results",
  "tool_name": "string (optional) — tool / MCP tool identifier",
  "passed": "boolean (optional) — guardrail result",
  "score": "number (optional) — guardrail score",
  "status": "OK | ERROR (optional, default OK)",
  "error": "string (optional) — error message when status is ERROR",
  "start": "string (optional) — ISO timestamp; defaults to the parent span's start",
  "end": "string (optional) — ISO timestamp; defaults to start + duration_ms",
  "duration_ms": "number (optional) — latency; end is derived from start + duration_ms",
  "metadata": { "any": "arbitrary key/values" },
  "attributes": { "neatlogs.llm.temperature": 0.7 },
  "logs": [{ "level": "info", "message": "string", "timestamp": "ISO (optional)" }],
  "children": [{ "name": "nested span", "kind": "TOOL" }]
}

{
  "success": true,
  "trace_id": "a1b2c3d4e5f6...",
  "spans": 2
}

{
  "error": "Validation error",
  "details": { "fieldErrors": { "name": ["Required"] } }
}

{
  "name": "answer",
  "kind": "LLM",
  "model": "gpt-4o",
  "input": "What is the capital of France?",
  "output": "Paris.",
  "tokens": { "prompt": 12, "completion": 3 },
  "attributes": {
    "neatlogs.llm.provider": "openai",
    "neatlogs.llm.temperature": 0.7,
    "neatlogs.llm.top_p": 0.9,
    "neatlogs.llm.max_tokens": 256
  }
}

{
  "name": "lookup_account",
  "kind": "TOOL",
  "tool_name": "get_account",
  "input": { "customer_id": "cust_123" },
  "output": { "status": "active" },
  "attributes": {
    "neatlogs.tool.description": "Fetch a customer account by id",
    "neatlogs.tool.parameters": "{\"customer_id\": \"string\"}"
  }
}

{
  "name": "retrieve_docs",
  "kind": "RETRIEVER",
  "query": "how do I reset my password?",
  "documents": ["doc: reset flow", "doc: account recovery"],
  "attributes": { "neatlogs.retriever.top_k": 5 }
}

{
  "name": "rerank",
  "kind": "RERANKER",
  "query": "reset password",
  "model": "cohere-rerank-v3",
  "documents": ["doc1", "doc2", "doc3"],
  "attributes": { "neatlogs.reranker.top_k": 2 }
}

{
  "name": "embed_query",
  "kind": "EMBEDDING",
  "model": "text-embedding-3-small",
  "input": "how do I reset my password?",
  "attributes": { "neatlogs.embedding.token_count": 8 }
}

{
  "name": "safety_check",
  "kind": "GUARDRAIL",
  "input": "user message to validate",
  "passed": false,
  "score": 0.82,
  "output": "blocked: prompt injection detected"
}

{
  "name": "research_agent",
  "kind": "AGENT",
  "input": "Plan the response",
  "output": "Drafted a 3-step plan",
  "attributes": {
    "neatlogs.agent.name": "researcher",
    "neatlogs.agent.role": "Gathers and synthesizes sources"
  }
}

{
  "name": "chat_turn",
  "project": "my-app",
  "attributes": {
    "neatlogs.session.id": "conv_42",
    "neatlogs.end_user.id": "u_812",
    "neatlogs.end_user.metadata": "{\"plan\":\"pro\"}"
  },
  "children": [
    { "name": "answer", "kind": "LLM", "model": "gpt-4o", "input": "hi", "output": "hello" }
  ]
}

import requests

BASE_URL = "https://ingest.neatlogs.com"
API_KEY = "your-write-key"

def send_trace(trace: dict):
    res = requests.post(
        f"{BASE_URL}/v1/trace",
        headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
        json=trace,
    )
    if res.status_code == 200:
        body = res.json()
        print(f"Trace sent: {body['trace_id']} ({body['spans']} spans)")
    else:
        print(f"Error: {res.status_code} - {res.text}")

send_trace({
    "name": "customer-support-agent",
    "project": "my-project",
    "input": {"question": "How do I reset my password?"},
    "children": [
        {
            "name": "call_llm",
            "kind": "LLM",
            "model": "gpt-4o",
            "input": "Generate a helpful response about password resets...",
            "output": "Click 'Forgot Password' on the login page...",
            "tokens": {"prompt": 240, "completion": 60},
        },
        {
            "name": "lookup_account",
            "kind": "TOOL",
            "tool_name": "get_account",
            "input": {"customer_id": "cust_123"},
            "output": {"status": "active"},
        },
    ],
})

async function sendTrace(trace: Record<string, unknown>) {
  const res = await fetch("https://ingest.neatlogs.com/v1/trace", {
    method: "POST",
    headers: {
      "x-api-key": process.env.NEATLOGS_WRITE_KEY ?? "",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(trace),
  });

  if (res.ok) {
    const { trace_id, spans } = await res.json();
    console.log(`Trace sent: ${trace_id} (${spans} spans)`);
  } else {
    console.error(`Error: ${res.status} - ${await res.text()}`);
  }
}

await sendTrace({
  name: "my-agent",
  project: "my-project",
  input: { query: "What is the weather?" },
  children: [
    {
      name: "call_weather_api",
      kind: "TOOL",
      tool_name: "get_weather",
      input: { location: "San Francisco" },
      output: { temperature: 72, condition: "sunny" },
    },
  ],
});

{
  "name": "workflow",
  "children": [
    {
      "name": "step_one",
      "kind": "CHAIN",
      "children": [
        { "name": "nested_tool", "kind": "TOOL", "tool_name": "search" }
      ]
    }
  ]
}

{
  "name": "api_call",
  "kind": "TOOL",
  "tool_name": "weather_api",
  "status": "ERROR",
  "error": "Connection timeout after 30s"
}

{
  "name": "rag_pipeline",
  "kind": "CHAIN",
  "logs": [
    { "level": "info", "message": "retrieved 42 documents" },
    { "level": "warning", "message": "low top score: 0.41" }
  ]
}

// Easiest: pass a duration, skip start/end
{ "name": "step", "duration_ms": 1200 }

// Or explicit ISO timestamps
{ "name": "step", "start": "2026-06-05T14:32:10Z", "end": "2026-06-05T14:32:15Z" }