Send traces

Neens ingests your agent’s traces over HTTP. It speaks standard OpenTelemetry (OTLP) and OpenInference, and also accepts a simple Neens-native raw JSON format. Pick whichever matches how your agent is already instrumented — all paths land in the same trace store.

At a glance

Authentication

Every request should authenticate with an agent API key (nk_live_…) as a bearer token:

Authorization: Bearer nk_live_your_key_here

The key alone scopes the request: it resolves to exactly one company and agent, so you don’t need to send an agent ID — and an authenticated request cannot be redirected to another agent by any header or body field. Create keys in Settings → API keys (see Getting started).

How a trace is attributed to an agent, in precedence order:

1. The API key’s agent — always wins when a key is supplied.
2. X-Neens-Project-Id header — only consulted when no key was supplied (keyless local/dev setups).
3. project_id field in the request body — same keyless fallback, lowest priority.
4. Otherwise the trace lands in the server’s default agent.

Choosing a format

All endpoints transparently decompress Content-Encoding: gzip (or deflate) bodies — the default for OTLP exporters and collectors. zstd is not supported and returns 415 Unsupported Media Type; fall back to gzip.

OpenTelemetry (recommended)

If your agent is instrumented with OpenTelemetry, point its OTLP/HTTP exporter at Neens and add your key as a header. No Neens-specific code required.

POST /v1/traces accepts both OTLP encodings:

• protobuf (Content-Type: application/x-protobuf) — the exporter default,
• JSON (Content-Type: application/json) — the OTLP/JSON shape.

export OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-neens-host>"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer nk_live_your_key_here"
python my_agent.py

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
 
exporter = OTLPSpanExporter(
    endpoint="https://<your-neens-host>/v1/traces",
    headers={"Authorization": "Bearer nk_live_your_key_here"},
)
# wire this exporter into your tracer provider as usual

curl -X POST "https://<your-neens-host>/v1/traces" \
  -H "Authorization: Bearer nk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceSpans": [{
      "resource": {"attributes": [
        {"key": "service.name", "value": {"stringValue": "support-bot"}}
      ]},
      "scopeSpans": [{"spans": [{
        "traceId": "W47/95gDgQPSabYzgT/GDA==",
        "spanId": "7uGbfsPBsXM=",
        "name": "chat gpt-4o",
        "startTimeUnixNano": "1752660000000000000",
        "endTimeUnixNano":   "1752660002000000000",
        "status": {"code": 1},
        "attributes": [
          {"key": "gen_ai.operation.name", "value": {"stringValue": "chat"}},
          {"key": "gen_ai.request.model",  "value": {"stringValue": "gpt-4o"}},
          {"key": "gen_ai.usage.input_tokens",  "value": {"intValue": "120"}},
          {"key": "gen_ai.usage.output_tokens", "value": {"intValue": "35"}}
        ]
      }]}]
    }]
  }'

A few OTLP-specific behaviors, all standards-compliant:

• The response is the OTLP ExportTraceServiceResponse envelope (protobuf or {} JSON, matching the request encoding) — 202 on the default async path, so a stock exporter or collector is happy without any Neens-specific handling.
• One OTLP export may carry spans from many traces (that’s how exporters batch); Neens groups spans by traceId and assembles one trace per id. The agent name comes from the resource’s service.name.
• An export with no resourceSpans (e.g. a collector heartbeat) is acknowledged as a successful no-op.
• The OTLP payload cap is 4 MiB (a 413 includes a Retry-After header so collectors back off and split batches).

Neens reads model, inputs/outputs, messages, token usage, tool calls, and conversation IDs from standard OTel GenAI and OpenInference attributes — per field, first match wins — so mixed instrumentation resolves correctly. See the attribute reference below.

OpenInference

If you export OpenInference span dicts directly (rather than over OTLP), post them to /ingest/openinference. The payload is an object with a top-level spans array; spans from multiple traces may be mixed in one payload and are grouped by context.trace_id.

curl -X POST "https://<your-neens-host>/ingest/openinference" \
  -H "Authorization: Bearer nk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "spans": [{
      "context": {"trace_id": "trace-001", "span_id": "span-1"},
      "name": "ChatCompletion",
      "parent_id": null,
      "start_time": "2026-07-16T10:00:00Z",
      "end_time":   "2026-07-16T10:00:02Z",
      "status_code": "OK",
      "attributes": {
        "openinference.span.kind": "LLM",
        "llm.model_name": "gpt-4o",
        "llm.token_count.prompt": 120,
        "llm.token_count.completion": 35,
        "llm.input_messages.0.message.role": "user",
        "llm.input_messages.0.message.content": "Where is my order?",
        "llm.output_messages.0.message.role": "assistant",
        "llm.output_messages.0.message.content": "Let me check that for you.",
        "session.id": "chat-42",
        "service.name": "support-bot"
      }
    }]
  }'

Each span needs context.trace_id, context.span_id, start_time, and end_time (ISO-8601). status_code is OK, ERROR, or unset; on errors, exception.message or error.message in attributes becomes the span’s error message. The agent name is taken from a service.name attribute. Spans with openinference.span.kind: "TOOL" also produce tool-call records automatically (tool name = span name, args/result from input.value/output.value).

Raw JSON (Neens-native)

The simplest option when you’re not using a tracing SDK. Post a session (one trace) and its spans directly. Only session.id is required — everything else has sensible defaults.

curl -X POST "https://<your-neens-host>/ingest/raw" \
  -H "Authorization: Bearer nk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "session": {"id": "trace-001", "agent_name": "my-agent"},
    "spans": [
      {"id": "span-1", "name": "llm.call", "kind": "llm",
       "input": "Hello?", "output": "Hi!", "model": "gpt-4o",
       "input_tokens": 12, "output_tokens": 4}
    ]
  }'

import requests
 
requests.post(
    "https://<your-neens-host>/ingest/raw",
    headers={"Authorization": "Bearer nk_live_your_key_here"},
    json={
        "session": {"id": "trace-001", "agent_name": "my-agent"},
        "spans": [
            {"id": "span-1", "name": "llm.call", "kind": "llm",
             "input": "Hello?", "output": "Hi!", "model": "gpt-4o",
             "input_tokens": 12, "output_tokens": 4},
        ],
    },
    timeout=10,
)

Raw payload reference

session — the trace header. Fields you supply are taken verbatim.

spans — the steps inside the trace (optional array). Only id is required per span.

tool_calls — optional array of tool/function invocations.

Batch

To send many traces in one request, post an array of raw payloads — or {"items": [...]} — to /ingest/batch. All items are attributed to the API key’s agent and buffered as one unit.

curl -X POST "https://<your-neens-host>/ingest/batch" \
  -H "Authorization: Bearer nk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '[
    {"session": {"id": "trace-001", "agent_name": "my-agent"}, "spans": []},
    {"session": {"id": "trace-002", "agent_name": "my-agent"}, "spans": []}
  ]'

A batch may be up to 8 MiB; each item is validated up front — a missing session or session.id returns 422 naming the offending item (e.g. batch item[1] session is missing required field 'id'). The batch must be non-empty.

With ?sync=true the batch is processed in-request and returns 200 {"session_ids": [...], "session_count": n, "span_count": n, "warnings": [...]}.

Grouping traces into sessions

Neens rolls individual traces up into a session when they share a conversation_id. Set the same ID on each turn of a multi-turn conversation and the turns appear together on the Sessions page, while remaining individually visible under Traces.

• Raw JSON: set session.conversation_id.
• OTLP / OpenInference: set any of gen_ai.conversation.id, session.id, conversation.id, or thread.id as a span attribute (first one found across the trace’s spans wins; empty strings are ignored).

{"session": {"id": "turn-2", "conversation_id": "chat-42", "agent_name": "support-bot"}}

A trace with no conversation ID is simply its own single-trace session. See Core concepts for the trace/session distinction.

How it works

Ingestion is asynchronous by default so your agent’s latency never depends on the Neens write path:

1. The edge authenticates the request, resolves the agent from the credential, and runs cheap structural validation (required top-level fields, size caps).
2. The payload is durably buffered and the request returns 202 immediately — for the /ingest/* endpoints the body is {"batch_id": "ing_…", "accepted": true}; /v1/traces answers with the standard OTLP response envelope instead.
3. A worker parses the payload (one session per trace ID), resolves semantic-convention attributes, and persists spans and tool calls. Traces appear in the UI within a few seconds.
4. If the buffer is unavailable the request is not acknowledged — you get 503 with Retry-After, and your exporter/collector retries from its own queue. Nothing is silently dropped.

Re-sending a trace is safe: sessions and spans are keyed by their IDs and upserted, so retries and duplicate deliveries update rather than duplicate. You may also supply your own Idempotency-Key header; otherwise a hash of the payload is used.

Add ?sync=true to any ingest endpoint to process in-request instead — useful for tests, first-trace verification, and low-volume backfills:

curl -X POST "https://<your-neens-host>/ingest/raw?sync=true" ...
# → 200 {"session_id": "trace-001", "span_count": 1, "warnings": []}

In sync mode you also get immediate 422s for deeper semantic problems (e.g. a malformed timestamp) that the async path would only detect after acceptance.

Reference

Response codes

Backpressure is per-agent: only the saturated agent is throttled, so a burst on one agent never slows another. The Retry-After value defaults to 5 seconds.

Which attributes Neens reads

Neens resolves each semantic field by probing the OTel GenAI and OpenInference vocabularies per field, in order — first non-empty value wins. Mixing vocabularies within one payload, or even one span, is fine.

Troubleshooting

A keyless request started returning 401

Ingest that used to be accepted with no credential now fails. This happens on a self-hosted Postgres deployment: a keyless write is refused rather than being filed into the unscoped default agent. (SQLite single-tenant dev installs are unaffected — keyless ingest still works there.)

The request that now fails:

curl -i -X POST "https://<your-neens-host>/ingest/raw" \
  -H "Content-Type: application/json" \
  -d '{"session": {"id": "trace-001"}, "spans": []}'

and the response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
 
{"detail": "Ingest requires an API key. Provide 'Authorization: Bearer nk_live_…'."}

The fix: send an agent API key. Mint one in the app under Settings → API keys — click Generate key and copy it immediately, it is shown once (full walkthrough: API keys). Then send it as a bearer token:

curl -i -X POST "https://<your-neens-host>/ingest/raw" \
  -H "Authorization: Bearer nk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"session": {"id": "trace-001"}, "spans": []}'

Expect 202 Accepted with a batch_id. The same header works on /v1/traces, /ingest/openinference and /ingest/batch — for an OTLP exporter or collector, set it via OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer nk_live_your_key_here".

The key carries the agent scope, so once you send one you can drop any X-Neens-Project-Id header or project_id body field you were relying on — the key wins over both.

Still stuck? See My traces aren’t showing up in the FAQ.

Verify

Open Traces in the app. Your traces appear within a few seconds; click one to inspect its spans, tool calls, inputs, outputs, latency, and cost. Once traces flow, continue to Traces & sessions and Judges.