> ## Documentation Index > Fetch the complete documentation index at: https://docs.coval.ai/llms.txt > Use this file to discover all available pages before exploring further. # Ingest OTLP traces > Ingest OpenTelemetry trace data and associate it with a simulation output or a monitoring conversation. The request body must be a standard OTLP `ExportTraceServiceRequest`, in protobuf binary (`application/x-protobuf`, the default for stock OTLP HTTP exporters) or JSON (`application/json`) format. See the [OTLP/HTTP specification](https://opentelemetry.io/docs/specs/otlp/#otlphttp) and [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto) for the wire format. Identify the target by providing exactly one of `X-Simulation-Id` or `X-Conversation-Id` (not both). ## OpenAPI ````yaml /api-reference/v1/traces-v1.yaml post /traces openapi: 3.0.3 info: title: Traces API version: 1.0.0 description: > OTLP/HTTP trace ingestion endpoint for Coval. Accepts native OpenTelemetry spans (protobuf or JSON, `ExportTraceServiceRequest` from `opentelemetry-proto`) and associates them with a simulation output or a monitoring conversation. Each request must identify its target via exactly one of: - `X-Simulation-Id` — for simulation flows (the simulation output ID). - `X-Conversation-Id` — for monitoring flows (the conversation ID returned by `POST /v1/conversations:submit`). For most use cases, the recommended client is the OpenTelemetry SDK itself (`OTLPSpanExporter` from `opentelemetry-exporter-otlp-proto-http` pointed at `https://api.coval.dev/v1/traces`). This OpenAPI spec exists for users who prefer to generate a typed HTTP client (e.g. with `openapi-python-client`). contact: name: Coval API Support url: https://coval.dev email: support@coval.dev servers: - url: https://api.coval.dev/v1 description: Production API security: - apiKey: [] tags: - name: Traces description: OTLP trace ingestion for simulations and monitoring conversations. paths: /traces: post: tags: - Traces summary: Ingest OTLP traces description: > Ingest OpenTelemetry trace data and associate it with a simulation output or a monitoring conversation. The request body must be a standard OTLP `ExportTraceServiceRequest`, in protobuf binary (`application/x-protobuf`, the default for stock OTLP HTTP exporters) or JSON (`application/json`) format. See the [OTLP/HTTP specification](https://opentelemetry.io/docs/specs/otlp/#otlphttp) and [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto) for the wire format. Identify the target by providing exactly one of `X-Simulation-Id` or `X-Conversation-Id` (not both). operationId: ingestTraces parameters: - name: X-Simulation-Id in: header required: false description: | Simulation output ID to associate the spans with. Use for simulation-based flows. Mutually exclusive with `X-Conversation-Id`. schema: type: string example: a1b2c3d4 - name: X-Conversation-Id in: header required: false description: | Conversation (Run) ID returned by `POST /v1/conversations:submit`. Use for monitoring flows. Mutually exclusive with `X-Simulation-Id`. schema: type: string example: 01H8XYZABCDEFG requestBody: required: true description: | OTLP `ExportTraceServiceRequest` payload — protobuf or JSON. content: application/x-protobuf: schema: type: string format: binary description: | OTLP/HTTP protobuf-encoded `ExportTraceServiceRequest`. This is the default content type emitted by the OpenTelemetry HTTP exporter (`opentelemetry-exporter-otlp-proto-http`). application/json: schema: type: object description: > OTLP/HTTP JSON-encoded `ExportTraceServiceRequest`. Top-level object with a `resourceSpans` array. See the [OTLP/HTTP specification](https://opentelemetry.io/docs/specs/otlp/#otlphttp) for the full schema. Field naming follows the OTLP JSON convention (camelCase or snake_case both accepted). example: resourceSpans: - resource: attributes: - key: service.name value: stringValue: my-agent scopeSpans: - scope: name: my-tracer spans: - traceId: 5b8aa5a2d2c872e8321cf37308d69df2 spanId: 051581bf3cb55c13 name: llm kind: 1 startTimeUnixNano: '1738000000000000000' endTimeUnixNano: '1738000001000000000' attributes: - key: metrics.ttfb value: doubleValue: 0.42 status: code: 1 responses: '200': description: Spans accepted and queued for ingestion. content: application/json: schema: type: object required: - status - simulation_output_id properties: status: type: string description: Always `ok` on success. example: ok simulation_output_id: type: string description: | The simulation output ID the spans were associated with. For monitoring flows submitted via `X-Conversation-Id`, this equals the conversation ID. example: a1b2c3d4 '400': description: | Invalid request body, missing identification header, or both `X-Simulation-Id` and `X-Conversation-Id` provided. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INVALID_ARGUMENT message: >- Missing required header: X-Simulation-Id or X-Conversation-Id details: - field: X-Simulation-Id description: Provide either X-Simulation-Id or X-Conversation-Id '401': $ref: '#/components/responses/Unauthorized' '403': description: API key lacks the `traces:write` scope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: PERMISSION_DENIED message: Insufficient permissions details: - field: permissions description: API key lacks the traces:write scope '404': description: | The simulation output or conversation does not exist, or it does not belong to your organization. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: Simulation output not found details: - field: X-Simulation-Id description: No simulation output found with this ID '500': $ref: '#/components/responses/InternalError' '503': description: | Service temporarily unavailable, typically because per-organization database routing has not yet activated. Retry after a brief delay. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL message: Service temporarily unavailable details: - description: >- Database routing is temporarily unavailable. Please retry. components: schemas: ErrorResponse: type: object description: Standard error response required: - error properties: error: type: object required: - code - message - details properties: code: type: string description: Machine-readable error code example: INVALID_ARGUMENT message: type: string description: Human-readable error message example: Invalid request parameters details: type: array description: Detailed error information items: type: object properties: field: type: string description: Field that caused the error example: X-Simulation-Id description: type: string description: Description of the error example: No simulation output found with this ID responses: Unauthorized: description: Authentication failed or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UNAUTHENTICATED message: Authentication failed details: - field: X-API-Key description: Invalid or missing API key InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL message: Internal server error details: - description: An unexpected error occurred while processing the request securitySchemes: apiKey: type: apiKey in: header name: X-API-Key description: Organization API key for authentication ````