> ## 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 run templates > Retrieve a paginated list of run templates. ## OpenAPI ````yaml /api-reference/v1/run-templates-v1.yaml get /run-templates openapi: 3.0.3 info: title: Coval Run Templates API version: 1.0.0 description: > Create and manage reusable run configurations for automated evaluations. Run templates define what to run (agent, persona, test set, metrics) and how to run it (iterations, concurrency, sampling). Use templates with Scheduled Runs to automate recurring 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: Run Templates description: CRUD operations for reusable run configurations paths: /run-templates: get: tags: - Run Templates summary: List run templates description: Retrieve a paginated list of run templates. operationId: listRunTemplates parameters: - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 50 description: Maximum number of results per page example: 50 - name: page_token in: query required: false schema: type: string description: Opaque pagination token from previous response - name: tag_filters in: query required: false style: form explode: true schema: type: array items: type: string maxItems: 20 description: > Filter run templates by tags. A resource matches when it has ALL the listed tags (AND-semantics). Repeat the parameter for each tag (e.g., `?tag_filters=nightly&tag_filters=voice`). example: - nightly responses: '200': description: Run templates retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ListRunTemplatesResponse' examples: success: $ref: '#/components/examples/ListRunTemplatesSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: schemas: ListRunTemplatesResponse: type: object required: - run_templates properties: run_templates: type: array items: $ref: '#/components/schemas/RunTemplateResource' next_page_token: type: string nullable: true description: Token for fetching next page (null if no more results) example: eyJvZmZzZXQiOjUwfQ== total_count: type: integer description: Total count of templates matching filter example: 25 RunTemplateResource: type: object description: Run template configuration resource. required: - name - id - display_name - agent_id - persona_id - test_set_id - create_time properties: name: type: string description: 'Resource name: "run-templates/{id}"' example: run-templates/abc123def456ghi789jklm id: type: string pattern: ^[A-Za-z0-9]{22}$ description: Run template resource ID example: abc123def456ghi789jklm display_name: type: string maxLength: 200 description: Human-readable template name example: Voice Agent Daily Test description: type: string description: Optional description of the template example: Daily regression test for voice agent agent_id: type: string pattern: ^[A-Za-z0-9]{22}$ description: Agent to test example: gk3jK9mPq2xRt5vW8yZaBc persona_id: type: string pattern: ^[A-Za-z0-9]{22}$ description: Simulated persona to use example: hL4kL0nQr3ySt6vX9zAcDd test_set_id: type: string pattern: ^[A-Za-z0-9]{8}$ description: Test set containing test cases example: aB1cD2eF metric_ids: type: array items: type: string pattern: ^[A-Za-z0-9]{22}$ description: Metrics to evaluate (uses agent defaults if empty) example: - iM5lM1oRs4zTu7wY0aBdEe mutation_ids: type: array items: type: string pattern: ^[A-Za-z0-9]{26}$ description: Mutations for A/B testing (optional) example: [] iteration_count: type: integer minimum: 1 maximum: 100 default: 1 description: Number of times to run each test case example: 3 concurrency: type: integer minimum: 1 maximum: 50 default: 1 description: Number of simulations to run concurrently example: 5 sub_sample_size: type: integer minimum: 0 default: 0 description: Number of test cases to randomly sample (0 = use all) example: 10 sub_sample_seed: type: integer nullable: true description: Random seed for reproducible sub-sampling example: 847293 metadata: type: object additionalProperties: true description: Custom metadata for tracking example: customer: campaign_id: q4_2025 tags: type: array description: Tags associated with this run template items: type: string default: [] example: - nightly - voice create_time: type: string format: date-time description: Creation timestamp (ISO 8601) example: '2025-10-14T12:00:00Z' update_time: type: string format: date-time nullable: true description: Last update timestamp (ISO 8601) example: '2025-10-15T14:30:00Z' ErrorResponse: type: object required: - error properties: error: type: object required: - code - message - details properties: code: type: string enum: - INVALID_ARGUMENT - UNAUTHENTICATED - NOT_FOUND - CONFLICT - INTERNAL example: INVALID_ARGUMENT message: type: string description: Human-readable error message example: Invalid request parameter details: type: array items: type: object properties: field: type: string nullable: true description: Field that caused the error example: agent_id description: type: string description: Detailed error description example: Agent not found or not accessible examples: ListRunTemplatesSuccess: summary: Successful list response value: run_templates: - name: run-templates/abc123def456ghi789jklm id: abc123def456ghi789jklm display_name: Voice Agent Daily Test description: Daily regression test for voice agent agent_id: gk3jK9mPq2xRt5vW8yZaBc persona_id: hL4kL0nQr3ySt6vX9zAcDd test_set_id: aB1cD2eF metric_ids: - iM5lM1oRs4zTu7wY0aBdEe mutation_ids: [] iteration_count: 3 concurrency: 5 sub_sample_size: 0 sub_sample_seed: null metadata: customer: campaign_id: q4_2025 create_time: '2025-10-14T12:00:00Z' update_time: '2025-10-15T14:30:00Z' next_page_token: null total_count: 1 responses: BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INVALID_ARGUMENT message: Invalid request body details: - field: display_name description: Field required Unauthorized: description: Authentication failed 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 securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication ````