> ## 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. # Delete or cancel conversation > Delete or cancel a conversation evaluation. ## OpenAPI ````yaml /api-reference/v1/conversations-v1.yaml delete /conversations/{conversation_id} openapi: 3.0.3 info: title: Coval Conversations API version: 1.0.0 description: | Submit and manage conversation evaluations. contact: name: Coval API Support email: support@coval.dev url: https://docs.coval.ai license: name: Proprietary url: https://coval.dev/terms servers: - url: https://api.coval.dev/v1 description: Production API security: - ApiKeyAuth: [] tags: - name: Conversations description: Submit and manage real-world conversation monitoring evaluations - name: Audio description: Upload audio for evaluation and access conversation audio files paths: /conversations/{conversation_id}: delete: tags: - Conversations summary: Delete or cancel conversation description: | Delete or cancel a conversation evaluation. operationId: deleteConversation parameters: - name: conversation_id in: path description: Unique conversation identifier required: true schema: type: string minLength: 22 maxLength: 26 example: gk3jK9mPq2xRt5vW8yZaBc responses: '200': description: Conversation deleted or cancelled successfully content: application/json: schema: $ref: '#/components/schemas/DeleteConversationResponse' examples: deleted: summary: Completed conversation deleted value: conversation: name: conversations/gk3jK9mPq2xRt5vW8yZaBc conversation_id: gk3jK9mPq2xRt5vW8yZaBc status: DELETED create_time: '2025-11-03T14:32:30Z' cancelled: summary: In-progress conversation cancelled value: conversation: name: conversations/hL4kL0nQr3ySt6vX9zAcDd conversation_id: hL4kL0nQr3ySt6vX9zAcDd status: CANCELLED create_time: '2025-11-03T15:20:18Z' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' components: schemas: DeleteConversationResponse: type: object required: - conversation properties: conversation: allOf: - $ref: '#/components/schemas/ConversationResource' description: > Conversation resource with updated status. Status will be either CANCELLED or DELETED depending on original status. ConversationResource: type: object properties: name: type: string description: Resource name in format "conversations/{conversation_id}" example: conversations/gk3jK9mPq2xRt5vW8yZaBc conversation_id: type: string description: Unique conversation identifier (22-26 characters) minLength: 22 maxLength: 26 example: gk3jK9mPq2xRt5vW8yZaBc status: $ref: '#/components/schemas/ConversationStatus' create_time: type: string format: date-time description: When conversation was submitted (ISO 8601) example: '2025-11-03T14:32:30Z' external_conversation_id: type: string description: External conversation ID from customer system example: external-call-7x8z9a occurred_at: type: string format: date-time description: When the conversation actually occurred (ISO 8601) example: '2025-11-03T14:32:00Z' has_audio: type: boolean description: | Whether audio is available for this conversation. Use GET /v1/conversations/{id}/audio to retrieve presigned URL. example: true agent_id: type: string nullable: true pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$ description: >- Agent resource ID (22-character ShortUUID), if one was provided at submission example: null persona_id: type: string nullable: true description: Reference to persona resource (typically null for monitoring) example: null source: description: >- The caller/initiating side of the conversation; null when not addressable. Only included in single-resource GET, not LIST. type: object nullable: true oneOf: - $ref: '#/components/schemas/PhoneEndpoint' - $ref: '#/components/schemas/SipEndpoint' - $ref: '#/components/schemas/WebsocketEndpoint' discriminator: propertyName: type destination: description: >- The agent side of the conversation; null when not addressable. Only included in single-resource GET, not LIST. type: object nullable: true oneOf: - $ref: '#/components/schemas/PhoneEndpoint' - $ref: '#/components/schemas/SipEndpoint' - $ref: '#/components/schemas/WebsocketEndpoint' discriminator: propertyName: type progress: allOf: - $ref: '#/components/schemas/ConversationProgress' description: Progress tracking (included when include_progress=true) metadata: type: object additionalProperties: true description: Customer-provided metadata example: campaign: q4-support channel: phone tags: type: array items: type: string description: Tags applied to this conversation example: - restaurant - support-tier-1 metric_ids: type: array items: type: string minLength: 22 maxLength: 26 description: > List of metric IDs configured for this conversation. Use GET /v1/conversations/{id}/metrics to retrieve computed metric values. example: - 29BlkepvvX19ebbLDB0y6Q - mymKvEg6ZA65srXbTX5wSM - fstokU4ev5UmT8sUBexiwV metric_outputs: type: array nullable: true description: > Full outputs matching the requested metric_id. Present only when the list request sets include=metric_outputs; omitted from the default summary view. items: $ref: '#/components/schemas/MetricOutputResource' error: type: string nullable: true description: Error message (only present if status=FAILED) example: null description: | Conversation resource object. ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Error code enum: - INVALID_ARGUMENT - UNAUTHENTICATED - NOT_FOUND - ALREADY_EXISTS - PAYLOAD_TOO_LARGE - INTERNAL_ERROR example: INVALID_ARGUMENT message: type: string description: Human-readable error message example: Missing required input data details: type: array items: $ref: '#/components/schemas/ErrorDetail' description: Additional error details default: [] ConversationStatus: type: string enum: - PENDING - IN_QUEUE - IN_PROGRESS - COMPLETED - FAILED - CANCELLED - DELETED description: | Current status of conversation evaluation. **Lifecycle:** - PENDING: Submitted, awaiting queue - IN_QUEUE: In run-setup-queue, awaiting worker - IN_PROGRESS: Evaluation running - COMPLETED: Successfully completed - FAILED: Encountered error - CANCELLED: User cancelled (via DELETE on PENDING/IN_PROGRESS) - DELETED: Deleted(via DELETE on COMPLETED/FAILED) PhoneEndpoint: type: object required: - type - value properties: type: type: string enum: - phone description: Endpoint kind discriminator value: type: string description: Phone number in E.164 format example: '+15551234567' SipEndpoint: type: object required: - type - value properties: type: type: string enum: - sip description: Endpoint kind discriminator value: type: string description: SIP URI example: sip:agent@voip.example.com WebsocketEndpoint: type: object required: - type - value properties: type: type: string enum: - websocket description: Endpoint kind discriminator value: type: string description: WebSocket URL example: wss://agent.example.com/stream ConversationProgress: type: object properties: total_metrics: type: integer description: Total number of metrics being evaluated example: 5 completed_metrics: type: integer description: Number of metrics completed successfully example: 5 failed_metrics: type: integer description: Number of metrics that failed evaluation example: 0 in_progress_metrics: type: integer description: Number of metrics currently running example: 0 MetricOutputResource: type: object required: - metric_output_id - metric_id - status properties: metric_output_id: type: string description: Unique metric output identifier (26-char ULID) minLength: 26 maxLength: 26 example: 01JCQR8Z9PQSTNVWXY12345678 metric_id: type: string description: Metric definition identifier (22-char ID) minLength: 22 maxLength: 26 example: 29BlkepvvX19ebbLDB0y6Q metric_version_ulid: type: string nullable: true minLength: 26 maxLength: 26 description: >- ULID of the metric version this output was scored against (null for outputs produced before metric versioning landed) example: 01JCQR8Z9PQSTNVWXY12345678 value: description: > Metric value (can be float, string, or list of strings depending on metric type, or null if failed) anyOf: - type: number - type: string - type: array items: type: string example: 2.35 status: type: string enum: - IN QUEUE - IN PROGRESS - COMPLETED - FAILED description: Status of metric computation example: COMPLETED explanation: type: string nullable: true description: >- The LLM judge's reasoning for this metric output, as a flat string. Null for metrics that produce no explanation (non-judge metrics) or when the output is not yet computed. This is a convenience surfacing of the reasoning that otherwise lives nested under result.llm.answer_explanation (or result.explanation); it is populated in both the list and single-output responses so callers do not have to request the full result object to read it. example: >- The agent never confirmed the caller's address before ending the call. result: type: object nullable: true additionalProperties: true description: >- Structured metric result. Its keys depend on the metric type — for LLM-judge metrics the judge's reasoning is at result.llm.answer_explanation and the evaluation prompt at result.llm.prompt. Null for metrics that produce no structured result. example: llm: answer_explanation: >- The agent never confirmed the caller's address before ending the call. prompt: Did the agent confirm the caller's address? description: | Simplified metric output for conversations API. ErrorDetail: type: object properties: field: type: string description: Field that caused the error example: transcript description: type: string description: Detailed description of the error example: At least one of transcript, audio, or audio_url must be provided responses: Unauthenticated: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UNAUTHENTICATED message: Invalid or missing API key details: [] NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversationNotFound: summary: Conversation not found value: error: code: NOT_FOUND message: Conversation not found details: [] simulationAccess: summary: Attempted to access simulation value: error: code: NOT_FOUND message: Conversation not found details: [] InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL_ERROR message: An internal error occurred while processing the request details: [] securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: | API key for authentication. ````