Reference

REST API

The SDK uses these endpoints for you. Call them directly when you send spans from another language or record deployments from CI without Python.

Authentication

Send your project API key in the x-api-key header. The key decides which project the data belongs to; there is no project field in the body. Base URL: your Lanternfish endpoint, for example https://your-lanternfish-endpoint.

curl -X POST "$LANTERNFISH_ENDPOINT/v1/deployments" \
  -H "x-api-key: $LANTERNFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version": "v1.8.2", "metadata": {"commit": "a1b2c3d"}}'

POST /v1/traces/batch

Sends up to 1,000 spans in one request; they may belong to different runs. Spans of the same run share a trace_id. Sending a span again is safe: a repeated span_id is ignored.

Times are ISO 8601; a time without a time zone is read as UTC.
A span counts as failed when otel.status_code is ERROR.
agent_name names the run's agent; token counts and the model are read from the gen_ai.* attributes.

[
  {
    "span_id": "a1b2c3d4e5f60718",
    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "parent_span_id": null,
    "name": "book-trip",
    "start_time": "2026-10-15T10:30:00Z",
    "end_time": "2026-10-15T10:30:02.4Z",
    "attributes": {
      "agent_name": "travel-agent",
      "gen_ai.request.model": "gpt-4o",
      "gen_ai.usage.input_tokens": 812,
      "gen_ai.usage.output_tokens": 164,
      "otel.status_code": "OK"
    },
    "user_id": "user_42",
    "session_id": "sess_9",
    "tags": {"plan": "pro"}
  }
]

Response: {"accepted": 1, "rejected": 0}. Runs over the plan limit are rejected one by one; when nothing could be stored the response is 402.

POST /v1/deployments

Records that a release went live, so briefings can compare before and after it. Fields: version (required, up to 100 characters), deployed_at (optional; defaults to the time of the request and may not be more than 5 minutes in the future) and metadata (up to 20 flat labels).

Response 201: {"id": "dep_…", "version": "v1.8.2", "deployed_at": "…"}

Limits

Span ingestion: 600 requests per minute per API key.
Other writes, such as recording a deployment: 30 requests per minute per key.
Request body: up to 8 MB.
Monthly runs depend on your plan; see Pricing.

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; a 429 also carries Retry-After.

Errors

HTTP error codes
400	A field is invalid, or end_time is before start_time.
401	The API key is missing, invalid or revoked.
402	The plan's monthly run limit is reached; detail.message says which limit.
413	More than 1,000 spans in one batch, or a body over 8 MB.
422	The body does not match the schema; detail lists the fields.
429	Too many requests this minute; wait for Retry-After seconds.

Error bodies have a detail field that says what was wrong.

SDK configuration