> ## 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 personas > Retrieve a paginated list of simulated personas with optional filtering and sorting. ## OpenAPI ````yaml /api-reference/v1/personas-v1.yaml get /personas openapi: 3.0.3 info: title: Coval Personas API version: 1.0.0 description: | Manage simulated personas used in voice and text evaluations. contact: name: Coval API Support url: https://coval.dev email: support@coval.dev servers: - url: https://api.coval.dev/v1 description: Production server security: - ApiKeyAuth: [] tags: - name: Personas description: Persona CRUD operations paths: /personas: get: tags: - Personas summary: List personas description: >- Retrieve a paginated list of simulated personas with optional filtering and sorting. operationId: listPersonas parameters: - name: page_size in: query description: Maximum number of personas to return (1-100) required: false schema: type: integer minimum: 1 maximum: 100 default: 50 - name: page_token in: query description: Token for retrieving the next page of results required: false schema: type: string - name: filter in: query description: > Filter expression syntax. Values may be unquoted or double-quoted. Values containing spaces must be quoted. Supported fields: - `name`: Filter by persona name (e.g., `name=Customer` or `name="Customer Support"`) - `create_time`: Filter by creation time (e.g., `create_time>"2025-01-01T00:00:00Z"`) - `update_time`: Filter by update time Examples: - `name="Customer Support"` (quoted - contains space) - `create_time>"2025-01-01T00:00:00Z"` required: false schema: type: string - name: order_by in: query description: | Field to order results by. Supported fields: `create_time`, `update_time`, `name` Formats: - Dash prefix: `-create_time` (descending) - Space separated: `create_time desc` (descending) - No prefix: `create_time` (ascending) required: false schema: type: string example: '-create_time' - name: tag_filters in: query description: > Filter personas by tags. A resource matches when it has ALL the listed tags (AND-semantics). Repeat the parameter for each tag (e.g., `?tag_filters=production&tag_filters=voice`). required: false style: form explode: true schema: type: array items: type: string maxItems: 20 example: - voice responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListPersonasResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' components: schemas: ListPersonasResponse: type: object required: - personas properties: personas: type: array items: $ref: '#/components/schemas/PersonaResource' next_page_token: type: string nullable: true description: Token for next page (null if no more pages) example: eyJvZmZzZXQiOjUwfQ== PersonaResource: type: object description: Persona resource representation returned by API responses. required: - resource_name - id - name - create_time properties: resource_name: type: string description: Resource name in format "personas/{persona_id}" example: personas/3zfmuDbVQsi4GaseDtiVcS id: type: string description: Unique persona identifier example: 3zfmuDbVQsi4GaseDtiVcS name: type: string description: Human-readable persona name example: Friendly Customer minLength: 1 maxLength: 200 persona_prompt: type: string nullable: true description: Instructions describing persona behavior and personality example: You are a friendly customer calling for technical support... voice_name: type: string nullable: true description: | Coval voice name. Use GET /personas/voices to discover available voices and their supported language codes. example: aria language_code: type: string nullable: true description: | BCP-47 language code for voice synthesis. Must be supported by the selected voice. Use GET /personas/voices to discover valid voice and language combinations. example: en-US background_sound: type: string nullable: true description: >- Built-in background sound id, or custom: for an active custom sound returned by GET /personas/background-sounds. example: office pattern: >- ^(off|office|lounge|crowd|airport|bus|playground|doorbell|train-arrival|portable-air-conditioner|skatepark|small-dog-bark|cafe|ferry-and-announcement|heavy-rain|moderate-wind|newborn-baby-crying|office-with-alarm|street-with-sirens|construction-work|backchanneling|custom:[A-Za-z0-9_-]+)$ background_sound_volume: type: number format: float nullable: true minimum: 0 description: >- Volume level for background sound (>= 0.0, no upper limit). Default is provider-controlled when omitted. example: 0.3 voice_volume: type: number format: float nullable: true minimum: 0 maximum: 2 description: >- Voice gain multiplier. 0.0 is silent, 1.0 is unchanged, and 2.0 is double volume. example: 1.25 voice_speed: type: number format: float nullable: true minimum: 0.25 maximum: 2 description: >- Voice speed multiplier accepted and stored from 0.25 to 2.0. 1.0 is unchanged. The selected voice may enforce a narrower effective range or ignore speed changes. example: 0.85 wait_seconds: type: number format: float nullable: true description: Response delay in seconds example: 0.5 minimum: 0.1 maximum: 2 conversation_initiation: type: string nullable: true description: Who initiates the conversation example: speak_first enum: - speak_first - wait_for_user multi_language_stt: type: boolean nullable: true description: > Enable multilingual speech-to-text so callers speaking languages other than the primary language_code are still transcribed accurately. Useful for personas simulating callers in bilingual regions or contact centers that serve diverse populations. example: true hold_music_timeout_seconds: type: number format: float nullable: true minimum: 5 maximum: 300 description: >- Disconnect after this many seconds of no speech (5-300). Used for hold music scenarios. example: 15 tags: type: array description: Tags associated with this persona items: type: string default: [] example: - voice - english create_time: type: string format: date-time description: Persona creation timestamp (ISO 8601) example: '2025-01-24T10:00:00Z' update_time: type: string format: date-time nullable: true description: Last update timestamp (ISO 8601) example: '2025-01-24T12:30:00Z' Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Error code example: INVALID_ARGUMENT message: type: string description: Human-readable error message example: Invalid voice_name 'invalid' responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_ARGUMENT message: Invalid language_code 'en-ZZ' Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHENTICATED message: Missing or invalid API key InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL message: An unexpected error occurred securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication ````