> ## 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. # Search trace-bearing calls > Searches calls with ingested traces across the authenticated organization. Filters match spans, while each result represents one simulation output or monitoring conversation. Results include matched span facets and aggregate status counts, but not raw attribute values. Pagination is cursor-based. Pass `next_cursor` from one response as `cursor` in the next request while keeping the filters and sort order unchanged. ## OpenAPI ````yaml /api-reference/v1/traces-v1.yaml post /traces/search openapi: 3.0.3 info: title: Traces API version: 1.0.0 description: > Ingest and inspect OpenTelemetry traces associated with Coval simulations and monitoring conversations. The API accepts native OTLP/HTTP spans and provides organization-scoped search, summary, and span read-back endpoints. Each ingestion 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 and organization-scoped trace reads. paths: /traces/search: post: tags: - Traces summary: Search trace-bearing calls description: > Searches calls with ingested traces across the authenticated organization. Filters match spans, while each result represents one simulation output or monitoring conversation. Results include matched span facets and aggregate status counts, but not raw attribute values. Pagination is cursor-based. Pass `next_cursor` from one response as `cursor` in the next request while keeping the filters and sort order unchanged. operationId: searchTraceCalls requestBody: required: false description: >- Search filters and cursor. An omitted or empty body searches all trace-bearing calls. content: application/json: schema: $ref: '#/components/schemas/TraceSearchRequest' responses: '200': description: A page of organization-scoped trace-bearing calls. content: application/json: schema: $ref: '#/components/schemas/TraceSearchResponse' '400': description: Invalid filters, pagination limit, or cursor. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': description: API key lacks the `traces:read` scope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': $ref: '#/components/responses/InternalError' '502': description: The trace store rejected the query. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Trace storage or organization routing is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: TraceSearchRequest: type: object additionalProperties: false properties: cursor: type: string nullable: true maxLength: 256 description: Opaque cursor returned as `next_cursor` by the previous page. limit: type: integer minimum: 1 maximum: 100 default: 25 filters: $ref: '#/components/schemas/TraceSearchFilters' TraceSearchResponse: type: object required: - items - total_count - aggregate_stats properties: items: type: array items: $ref: '#/components/schemas/TraceSearchCallResult' total_count: type: integer minimum: 0 next_cursor: type: string nullable: true aggregate_stats: $ref: '#/components/schemas/TraceSearchAggregateStats' 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 TraceSearchFilters: type: object properties: start_date: type: string nullable: true description: Include spans at or after this ISO 8601 timestamp. example: '2026-07-30T00:00:00Z' end_date: type: string nullable: true description: Include spans at or before this ISO 8601 timestamp. example: '2026-07-31T00:00:00Z' span_name: type: string nullable: true maxLength: 500 description: Case-insensitive substring match on span name. provider: type: string nullable: true maxLength: 500 description: Case-insensitive substring match on detected provider. status: type: string nullable: true enum: - ERROR - OK - UNSET attribute_filters: type: array nullable: true maxItems: 10 items: $ref: '#/components/schemas/TraceSearchAttributeFilter' duration_ms_min: type: number nullable: true minimum: 0 duration_ms_max: type: number nullable: true minimum: 0 sort_by: type: string nullable: true enum: - newest - oldest - slowest - fastest default: newest agent_id: type: string nullable: true minLength: 1 maxLength: 64 test_set_id: type: string nullable: true minLength: 1 maxLength: 64 TraceSearchCallResult: type: object required: - simulation_output_id - run_id - latest_matched_timestamp_ms - first_matched_timestamp_ms - matched_span_count - total_span_count - error_span_count - ok_span_count - unset_span_count - overall_status properties: simulation_output_id: type: string run_id: type: string latest_matched_timestamp_ms: type: integer format: int64 first_matched_timestamp_ms: type: integer format: int64 matched_span_count: type: integer minimum: 0 total_span_count: type: integer minimum: 0 error_span_count: type: integer minimum: 0 ok_span_count: type: integer minimum: 0 unset_span_count: type: integer minimum: 0 overall_status: type: string enum: - ERROR - OK - UNSET matched_span_names: type: array items: type: string matched_provider_names: type: array items: type: string matched_service_names: type: array items: type: string matched_scope_names: type: array items: type: string TraceSearchAggregateStats: type: object required: - error_count - error_rate properties: error_count: type: integer minimum: 0 error_rate: type: integer minimum: 0 maximum: 100 description: Percentage of matching calls containing at least one error span. TraceSearchAttributeFilter: type: object required: - key properties: key: type: string minLength: 1 maxLength: 500 operator: type: string enum: - contains - eq - exists - gt - gte - lt - lte default: contains value: type: string nullable: true maxLength: 500 description: Optional for `exists`; required for value comparisons. 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 ````