Ingest reference.

Endpoint

POST https://www.twotail.ai/api/v1/traces
X-API-Key: <TWOTAIL_API_KEY>
Content-Type: application/json

The body is standard OTLP/JSON (the OpenTelemetry OTLP/HTTP JSON encoding). OTLP protobuf, OTLP/gRPC, and gzip-compressed bodies are not accepted. API keys are created in the app under API Keys and sent in the X-API-Key header.

Response

{
  "success": true,
  "message": "Successfully ingested 12 spans from OTel format",
  "spans_inserted": 12
}

Spans that are valid OTLP but fail TwoTail's mapping are skipped, not rejected: the request still succeeds and the skip count usually shows in message as "(N malformed spans skipped)". spans_inserted is the authoritative count. A span missing required fields (traceId, spanId, name, timestamps) fails request validation instead, and the whole request is rejected with 422.

Errors

Retries

Retrying a batch is safe. A span resent with the same spanId refreshes that span's outputs, end time, tokens, cost, and error status instead of duplicating it; its name, trace, parent, start time, inputs, and metadata keep their first-write values. Span ids must therefore be unique across all your traces, not just within one trace: reusing an id for a different span corrupts the stored record.

Payload shape

{
  "resourceSpans": [{
    "resource": {
      "attributes": [
        {"key": "service.name", "value": {"stringValue": "my-agent"}}
      ]
    },
    "scopeSpans": [{
      "spans": [{
        "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
        "spanId": "00f067aa0ba902b7",
        "parentSpanId": null,
        "name": "chat_completion",
        "startTimeUnixNano": 1783977600000000000,
        "endTimeUnixNano": 1783977600100000000,
        "attributes": [
          {"key": "gen_ai.system", "value": {"stringValue": "openai"}}
        ],
        "status": {"code": 1}
      }]
    }]
  }]
}

Span typing

TwoTail assigns each span a type and, where it can, a purpose. Both drive filtering, cost attribution, and analysis.

Rules are checked in order: gen_ai attributes, then tool.name, then name keywords.

Attributes TwoTail reads

TwoTail understands several instrumentation conventions side by side. Send whichever your stack produces; you don't need to translate between them.

Values for these keys that arrive as stringified JSON are parsed into structured objects, so message lists and tool arguments render properly in the trace view. The exception is gen_ai.prompt, which is stored verbatim: prefer gen_ai.input.messages for structured message lists.

Everything else

Attributes TwoTail doesn't specifically read are preserved as span metadata and stay queryable in analysis: business ids like user.id or document.id, feature flags, whatever you send. Values keep the type you sent them with. One consequence worth knowing: a flag sent as the string "1" is compared as a string, not the number 1, when you later ask questions about it.

Sessions

For multi-turn agents, TwoTail groups traces into sessions by conversation id: one trace per turn, the same conversation id on every turn. Set gen_ai.conversation.id on the spans of each turn.

Aliases accepted, first match wins: gen_ai.conversation.id, session.id, session_id, sessionId, conversation.id, conversation_id, thread.id, thread_id.

Evals

Send evaluations as child spans of the span they evaluate: set the eval span's parentSpanId to the evaluated span's id.

• Naming. Start the span name with eval. or eval_ (e.g. eval.relevance), or use a name containing "evaluation" or "evaluate", so the span gets purpose evaluation.
• Scores. Use the OTel GenAI eval conventions: gen_ai.evaluation.name, gen_ai.evaluation.score.value (numeric), gen_ai.evaluation.score.label (e.g. "pass"), gen_ai.evaluation.explanation. Legacy eval.name / eval.score / eval.passed / eval.reason are still accepted.
• LLM judges. If an LLM produces the evaluation, include gen_ai.* attributes on the eval span so the judge call itself is captured with model, tokens, and cost.

Cost

Cost is attributed to the exact LLM span that spent it; it is not rolled up onto parents, so grouping and slicing spend stays accurate at any level.

• Explicit wins. If you send a nonzero gen_ai.usage.cost, that value is used as-is; a cost of 0 falls back to the computed estimate.
• Otherwise computed. Cost is derived from token counts when gen_ai.request.model matches a model in TwoTail's pricing table of known models. The match is exact: a provider-specific alias or dated snapshot name that isn't recognized yields no cost rather than a wrong guess.
• Cached tokens priced. Cached input tokens (see attributes) are priced at the provider's cached rate where TwoTail has one for the model, otherwise at a default of 10% of the input rate.
• Recommendation. Send canonical model names, or send gen_ai.usage.cost explicitly if you use gateways or exotic model ids.

Gotchas

• Errors are status-code only. A span is an error if and only if status.code is 2. Exception text in the name or attributes does not mark it.
• Nanoseconds. Timestamps in milliseconds or seconds are accepted silently and produce 1970-era spans.
• Token values must be numeric. Malformed token counts coerce to 0 rather than erroring.
• Strings compare as strings. Custom flags sent as "0"/"1" strings are compared as text in analysis, not as numbers.
• Span ids must be unique across all your traces. Resending a span id refreshes the original span; reusing one for a different span corrupts it.
• Watch spans_inserted. It is the authoritative count of what landed; don't rely on the message text alone.