> ## 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. # List conversations > List conversations with optional filtering, pagination, and ordering. ## OpenAPI ````yaml /api-reference/v1/conversations-v1.yaml get /conversations 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: get: tags: - Conversations summary: List conversations description: | List conversations with optional filtering, pagination, and ordering. operationId: listConversations parameters: - name: page_size in: query description: Maximum number of conversations to return (1-250) required: false schema: type: integer minimum: 1 maximum: 250 default: 50 - name: page_token in: query description: Token for retrieving next page (from previous response) required: false schema: type: string example: eyJvZmZzZXQiOiA1MH0= - name: filter in: query description: > Filter expression syntax. **Operators:** `=`, `!=`, `>`, `<`, `>=`, `<=`, `AND`, `OR` Values may be unquoted or double-quoted. Values containing spaces must be quoted. **Fields:** - `status` - PENDING, IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELLED, DELETED - `external_conversation_id` - Your system's conversation ID - `create_time` - ISO 8601 timestamp - `occurred_at` - ISO 8601 timestamp - `metadata.{key}` - Custom metadata fields **Examples:** - `status=COMPLETED` - `create_time>"2025-11-01T00:00:00Z"` - `status=COMPLETED AND occurred_at>="2025-11-01T00:00:00Z"` - `external_conversation_id=external-call-abc` required: false schema: type: string examples: byStatus: value: status=COMPLETED summary: Filter by status byDateRange: value: >- create_time>="2025-11-01T00:00:00Z" AND create_time<"2025-12-01T00:00:00Z" summary: Filter by date range byExternalId: value: external_conversation_id=external-call-7x8z9a summary: Filter by external ID byMetadata: value: metadata.channel=phone summary: Filter by custom metadata combined: value: status=COMPLETED AND metadata.department=sales summary: Combined filters with metadata - name: order_by in: query description: | Sort field with optional `-` prefix for descending order. **Fields:** `create_time`, `occurred_at`, `status` **Examples:** - `create_time` (ascending) - `-create_time` (descending, most recent first) - `-occurred_at` (most recent conversations first) required: false schema: type: string default: '-occurred_at' examples: newest: value: '-create_time' summary: Newest first oldest: value: create_time summary: Oldest first recentConversations: value: '-occurred_at' summary: Most recent conversations - name: view in: query description: > Set to `metric_breakdown` to return an aggregate of one metric's scores grouped by a `customer_metadata` key (e.g. vendor), computed over the whole scored monitoring corpus, instead of the conversation list. Requires `metric_id` and `group_by_metadata`; the response is a metric-breakdown object (`{view, metric_id, group_by_metadata, aggregation, breakdown:[{metadata_value, value, count}], total_count}`). required: false schema: type: string enum: - metric_breakdown - name: metric_id in: query description: > Metric to aggregate when `view=metric_breakdown`, or the metric whose full outputs should be embedded when `include=metric_outputs`. required: false schema: type: string - name: include in: query description: > Set to `metric_outputs` to embed full outputs for `metric_id` on every conversation in the returned page. Omitted by default to keep list payloads small. required: false schema: type: string enum: - metric_outputs - name: group_by_metadata in: query description: >- Required when `view=metric_breakdown`: the customer_metadata key to group by (e.g. nlp_provider). required: false schema: type: string example: nlp_provider - name: aggregation in: query description: > Aggregation for `view=metric_breakdown`. Defaults to `success` (a YES/NO success rate) for binary/string metrics and `avg` (numeric mean) for float metrics. required: false schema: type: string enum: - success - avg - name: start_date in: query description: >- Optional ISO-8601 lower bound (occurred_at) for `view=metric_breakdown`. required: false schema: type: string format: date-time - name: end_date in: query description: >- Optional ISO-8601 upper bound (occurred_at) for `view=metric_breakdown`. required: false schema: type: string format: date-time responses: '200': description: >- List of conversations, or a metric breakdown when `view=metric_breakdown` content: application/json: schema: oneOf: - $ref: '#/components/schemas/ListConversationsResponse' - $ref: '#/components/schemas/MetricBreakdownResponse' examples: withResults: summary: List with multiple conversations value: conversations: - name: conversations/gk3jK9mPq2xRt5vW8yZaBc conversation_id: gk3jK9mPq2xRt5vW8yZaBc status: COMPLETED create_time: '2025-11-03T14:32:30Z' external_conversation_id: external-call-7x8z9a occurred_at: '2025-11-03T14:32:00Z' has_audio: true metadata: campaign: q4-support - name: conversations/hL4kL0nQr3ySt6vX9zAcDd conversation_id: hL4kL0nQr3ySt6vX9zAcDd status: IN_PROGRESS create_time: '2025-11-03T15:20:18Z' external_conversation_id: twilio-call-CA9m2k4p occurred_at: '2025-11-03T15:20:00Z' has_audio: true metadata: department: sales next_page_token: eyJvZmZzZXQiOiA1MH0= empty: summary: Empty result set value: conversations: [] next_page_token: null metricBreakdown: summary: Metric breakdown grouped by a customer_metadata key value: view: metric_breakdown metric_id: 29BlkepvvX19ebbLDB0y6Q group_by_metadata: nlp_provider aggregation: success breakdown: - metadata_value: decagon value: 0.93 count: 412 - metadata_value: sierra value: 0.88 count: 377 total_count: 789 '400': $ref: '#/components/responses/InvalidArgument' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' components: schemas: ListConversationsResponse: type: object required: - conversations properties: conversations: type: array items: $ref: '#/components/schemas/ConversationResource' description: List of conversations (max page_size items) next_page_token: type: string nullable: true description: | Token for retrieving next page. null indicates last page. Pass this value in page_token query parameter for next page. example: eyJvZmZzZXQiOiA1MH0= MetricBreakdownResponse: type: object required: - view - metric_id - group_by_metadata - aggregation - breakdown - total_count properties: view: type: string enum: - metric_breakdown description: Response discriminator for the metric breakdown view metric_id: type: string description: The metric the breakdown was computed for example: 29BlkepvvX19ebbLDB0y6Q group_by_metadata: type: string description: The customer_metadata key the breakdown is grouped by example: nlp_provider aggregation: type: string enum: - success - avg description: Aggregation applied to the metric breakdown: type: array description: One row per metadata value, ordered by count descending items: $ref: '#/components/schemas/MetricBreakdownRow' total_count: type: integer description: Total scored monitoring conversations across all groups example: 789 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. MetricBreakdownRow: type: object required: - metadata_value - count properties: metadata_value: type: string description: The customer_metadata value for this group (for example, a vendor) example: decagon value: type: number nullable: true description: >- Aggregate value: success rate in [0,1] for aggregation=success, else the numeric mean example: 0.93 count: type: integer description: Number of scored monitoring conversations in this group example: 412 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: InvalidArgument: description: Invalid request arguments content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingInput: summary: Missing required input value: error: code: INVALID_ARGUMENT message: Missing required input data details: - field: transcript description: At least one of transcript or audio_url must be provided invalidFilter: summary: Invalid filter expression value: error: code: INVALID_ARGUMENT message: Invalid filter expression details: - field: filter description: >- Unknown field 'invalid_field'. Valid fields: status, create_time, occurred_at, external_conversation_id invalidPageSize: summary: Invalid page_size value: error: code: INVALID_ARGUMENT message: Invalid page_size details: - field: page_size description: page_size must be between 1 and 250 audioFormatInvalid: summary: Unsupported audio format value: error: code: INVALID_ARGUMENT message: >- Unsupported audio format: MP4. Only WAV and MP3 files are supported. details: - field: audio_url description: >- Audio format detected as MP4 via magic byte analysis. Convert to WAV or MP3. audioTooShort: summary: Audio duration too short value: error: code: INVALID_ARGUMENT message: 'Audio too short: 3.0 seconds. Minimum duration is 5 seconds.' details: - field: audio_url description: >- Audio file duration is below the 5 second minimum requirement audioTooLong: summary: Audio duration too long value: error: code: INVALID_ARGUMENT message: >- Audio too long: 75.0 minutes. Maximum duration is 60 minutes. details: - field: audio_url description: Audio file duration exceeds the 1 hour maximum limit audioTooLarge: summary: Audio file size too large value: error: code: INVALID_ARGUMENT message: 'Audio file too large: 250.0 MB. Maximum size is 200 MB.' details: - field: audio_url description: Audio file size exceeds 200 MB limit audioEmpty: summary: Empty audio file value: error: code: INVALID_ARGUMENT message: Audio file is empty. details: - field: audio_url description: Audio file contains no data audioCorrupt: summary: Corrupt or invalid audio file value: error: code: INVALID_ARGUMENT message: >- Invalid or corrupt audio file. Unable to read audio metadata. details: - field: audio_url description: Audio file headers could not be read or are corrupted 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. ````