{"openapi":"3.1.0","info":{"title":"telemetry.dev Ingest API","version":"1.0.0","description":"OTLP/HTTP ingest for telemetry.dev, the observability platform for AI and LLM apps. Every model call, tool step, and retrieval arrives as OpenTelemetry spans with tokens, cost, latency, and errors attached. The API is versioned by URL path (/v1). Deprecation policy: breaking changes ship under a new /vN prefix, this document announces each deprecation, and a deprecated version answers with a Sunset header once its removal date is set. Authenticate with a project API key (created in the dashboard after signup). Setup guides for SDKs and frameworks: https://telemetry.dev/integrations — site overview for agents: https://telemetry.dev/llms.txt"},"servers":[{"url":"https://ingest.telemetry.dev","description":"Production ingest"}],"tags":[{"name":"ingest","description":"OTLP/HTTP signal export"},{"name":"ops","description":"Service health"}],"paths":{"/health":{"get":{"operationId":"getIngestHealth","tags":["ops"],"summary":"Health check","description":"Liveness probe for the ingest service.","security":[],"responses":{"200":{"description":"Service is up.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}}}}},"/v1/traces":{"post":{"operationId":"exportTraces","tags":["ingest"],"summary":"Export traces (OTLP/HTTP)","description":"Accepts one OTLP/HTTP ExportTraceServiceRequest payload and stores it for the project that owns the API key. Use `application/x-protobuf` for binary OTLP or `application/json` for OTLP/JSON. The API accepts gzip compression with `Content-Encoding: gzip`. It treats identity as absent. The raw body limit is 4 MiB. The decompressed body limit is 16 MiB. A successful request accepts the full batch. An error rejects the full request. The response uses the request encoding. A protobuf request receives an empty binary ExportTraceServiceResponse. A JSON request receives `{}`. A JSON error contains a message object. A protobuf error contains a Status message. An API key applies to one environment or to all environments. An environment mismatch returns 403.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/x-protobuf":{"schema":{"type":"string","format":"binary"},"description":"Binary protobuf ExportTraceServiceRequest."},"application/json":{"schema":{"type":"object","additionalProperties":true},"description":"OTLP/JSON ExportTraceServiceRequest. The payload must decode as ExportTraceServiceRequest; an empty batch (no trace records) is rejected with 400."}}},"parameters":[{"name":"Content-Encoding","in":"header","required":false,"schema":{"type":"string","enum":["gzip","identity"]},"description":"gzip compresses the request body; identity (or absence) sends it raw."}],"responses":{"200":{"description":"The server accepted the full batch. The body is an empty ExportTraceServiceResponse for protobuf or {} for JSON. The server does not return partial success. An error rejects the full request. Free-plan trace responses include RateLimit-Limit and RateLimit-Reset headers.","headers":{"RateLimit-Limit":{"description":"Monthly cap for free-plan projects, enforced against the stored span count; absent for paid plans.","schema":{"type":"string"}},"RateLimit-Reset":{"description":"Seconds until the monthly cap resets (next UTC month).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Payload did not decode, decompression failed, or the batch contained no records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"The Authorization header is missing or is not `Bearer <project API key>`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"403":{"description":"The API key applies to a different environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"409":{"description":"The trace ID already belongs to another project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"413":{"description":"The body is more than 4 MiB raw or 16 MiB decompressed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"415":{"description":"Content-Type is not application/x-protobuf or application/json, or Content-Encoding is not gzip or identity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"429":{"description":"The monthly ingestion quota is exceeded.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"500":{"description":"An internal operation or the authentication lookup failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"503":{"description":"Persistence failed. You can safely try the request again.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}}}}},"/v1/logs":{"post":{"operationId":"exportLogs","tags":["ingest"],"summary":"Export logs (OTLP/HTTP)","description":"Accepts one OTLP/HTTP ExportLogsServiceRequest payload and stores it for the project that owns the API key. Use `application/x-protobuf` for binary OTLP or `application/json` for OTLP/JSON. The API accepts gzip compression with `Content-Encoding: gzip`. It treats identity as absent. The raw body limit is 4 MiB. The decompressed body limit is 16 MiB. A successful request accepts the full batch. An error rejects the full request. The response uses the request encoding. A protobuf request receives an empty binary ExportLogsServiceResponse. A JSON request receives `{}`. A JSON error contains a message object. A protobuf error contains a Status message. An API key applies to one environment or to all environments. An environment mismatch returns 403.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/x-protobuf":{"schema":{"type":"string","format":"binary"},"description":"Binary protobuf ExportLogsServiceRequest."},"application/json":{"schema":{"type":"object","additionalProperties":true},"description":"OTLP/JSON ExportLogsServiceRequest. The payload must decode as ExportLogsServiceRequest; an empty batch (no log records) is rejected with 400."}}},"parameters":[{"name":"Content-Encoding","in":"header","required":false,"schema":{"type":"string","enum":["gzip","identity"]},"description":"gzip compresses the request body; identity (or absence) sends it raw."}],"responses":{"200":{"description":"The server accepted the full batch. The body is an empty ExportLogsServiceResponse for protobuf or {} for JSON. The server does not return partial success. An error rejects the full request.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Payload did not decode, decompression failed, or the batch contained no records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"The Authorization header is missing or is not `Bearer <project API key>`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"403":{"description":"The API key applies to a different environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"409":{"description":"The trace ID already belongs to another project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"413":{"description":"The body is more than 4 MiB raw or 16 MiB decompressed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"415":{"description":"Content-Type is not application/x-protobuf or application/json, or Content-Encoding is not gzip or identity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"429":{"description":"The monthly ingestion quota is exceeded.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"500":{"description":"An internal operation or the authentication lookup failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"503":{"description":"Persistence failed. You can safely try the request again.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}}}}},"/v1/metrics":{"post":{"operationId":"exportMetrics","tags":["ingest"],"summary":"Export metrics (OTLP/HTTP)","description":"Accepts one OTLP/HTTP ExportMetricsServiceRequest payload and stores it for the project that owns the API key. Use `application/x-protobuf` for binary OTLP or `application/json` for OTLP/JSON. The API accepts gzip compression with `Content-Encoding: gzip`. It treats identity as absent. The raw body limit is 4 MiB. The decompressed body limit is 16 MiB. A successful request accepts the full batch. An error rejects the full request. The response uses the request encoding. A protobuf request receives an empty binary ExportMetricsServiceResponse. A JSON request receives `{}`. A JSON error contains a message object. A protobuf error contains a Status message. An API key applies to one environment or to all environments. An environment mismatch returns 403.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/x-protobuf":{"schema":{"type":"string","format":"binary"},"description":"Binary protobuf ExportMetricsServiceRequest."},"application/json":{"schema":{"type":"object","additionalProperties":true},"description":"OTLP/JSON ExportMetricsServiceRequest. The payload must decode as ExportMetricsServiceRequest; an empty batch (no metric records) is rejected with 400."}}},"parameters":[{"name":"Content-Encoding","in":"header","required":false,"schema":{"type":"string","enum":["gzip","identity"]},"description":"gzip compresses the request body; identity (or absence) sends it raw."}],"responses":{"200":{"description":"The server accepted the full batch. The body is an empty ExportMetricsServiceResponse for protobuf or {} for JSON. The server does not return partial success. An error rejects the full request.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Payload did not decode, decompression failed, or the batch contained no records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"The Authorization header is missing or is not `Bearer <project API key>`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"403":{"description":"The API key applies to a different environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"409":{"description":"The trace ID already belongs to another project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"413":{"description":"The body is more than 4 MiB raw or 16 MiB decompressed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"415":{"description":"Content-Type is not application/x-protobuf or application/json, or Content-Encoding is not gzip or identity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"429":{"description":"The monthly ingestion quota is exceeded.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"500":{"description":"An internal operation or the authentication lookup failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"503":{"description":"Persistence failed. You can safely try the request again.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Project API key (`td_live_...`), scoped to one environment or to all environments. Create keys in the dashboard under a project's API keys page."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error detail."}},"required":["message"],"description":"The error object. A JSON response contains `{\"message\": \"...\"}`. A protobuf response contains a binary protobuf Status message. The Status `message` field contains the same human-readable detail."}}}}