> ## Documentation Index > Fetch the complete documentation index at: https://docs.pandaprobe.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Eval Run > Create a filtered eval run. Resolves traces matching the provided filters, optionally samples a fraction of them, then dispatches a background Celery task to run the requested metrics asynchronously via an LLM judge. **Request body fields:** - **name** *(string, optional)*: Human-readable label, e.g. ``"Weekly prod eval"``. - **metrics** *(string[], required)*: Metric names to run. Get available names from ``GET /evaluations/trace-metrics``. Example: ``["task_completion", "tool_correctness"]``. - **filters** *(object, optional)*: Trace selection filters. All fields optional: - **date_from**: ISO 8601 datetime, e.g. ``"2025-01-15T00:00:00Z"``. Includes traces started on or after this time. - **date_to**: ISO 8601 datetime. Includes traces started before this time (exclusive). - **status**: One of ``PENDING``, ``RUNNING``, ``COMPLETED``, ``ERROR``. - **session_id**: Exact session ID string. - **user_id**: Exact user ID string. - **tags**: Array of strings, e.g. ``["production", "v2"]``. Matches traces with ANY tag. - **name**: Substring match on trace name (case-insensitive). - **sampling_rate** *(float, optional, default 1.0)*: Fraction of matching traces to evaluate. ``1.0`` = all, ``0.1`` = random 10%. - **model** *(string, optional)*: LLM model override, e.g. ``"openai/gpt-4o"``. Uses system default if null. Auth: ``Bearer`` + ``X-Project-ID`` | ``X-API-Key`` + ``X-Project-Name`` Rate limit: ``50/min`` ## OpenAPI ````yaml /openapi.json post /evaluations/trace-runs openapi: 3.1.0 info: title: PandaProbe API description: >- Open-source agent engineering platform — trace LLM calls, evaluate agent performance, and monitor AI pipelines. version: 0.1.0 contact: name: PandaProbe url: https://www.pandaprobe.com email: support@pandaprobe.com servers: - url: https://api.pandaprobe.com description: Production security: [] tags: - name: health description: Service health and readiness probes. - name: user description: Authenticated user profile. - name: traces description: Trace ingestion, querying, updating, and analytics. - name: sessions description: Session-based trace aggregation and analytics. - name: evaluations description: Evaluation runs, scores, analytics, and monitoring. - name: organizations description: Organization management and membership. - name: projects description: Project CRUD within organizations. - name: api-keys description: API key lifecycle management. paths: /evaluations/trace-runs: post: tags: - evaluations summary: Create Eval Run description: >- Create a filtered eval run. Resolves traces matching the provided filters, optionally samples a fraction of them, then dispatches a background Celery task to run the requested metrics asynchronously via an LLM judge. **Request body fields:** - **name** *(string, optional)*: Human-readable label, e.g. ``"Weekly prod eval"``. - **metrics** *(string[], required)*: Metric names to run. Get available names from ``GET /evaluations/trace-metrics``. Example: ``["task_completion", "tool_correctness"]``. - **filters** *(object, optional)*: Trace selection filters. All fields optional: - **date_from**: ISO 8601 datetime, e.g. ``"2025-01-15T00:00:00Z"``. Includes traces started on or after this time. - **date_to**: ISO 8601 datetime. Includes traces started before this time (exclusive). - **status**: One of ``PENDING``, ``RUNNING``, ``COMPLETED``, ``ERROR``. - **session_id**: Exact session ID string. - **user_id**: Exact user ID string. - **tags**: Array of strings, e.g. ``["production", "v2"]``. Matches traces with ANY tag. - **name**: Substring match on trace name (case-insensitive). - **sampling_rate** *(float, optional, default 1.0)*: Fraction of matching traces to evaluate. ``1.0`` = all, ``0.1`` = random 10%. - **model** *(string, optional)*: LLM model override, e.g. ``"openai/gpt-4o"``. Uses system default if null. Auth: ``Bearer`` + ``X-Project-ID`` | ``X-API-Key`` + ``X-Project-Name`` Rate limit: ``50/min`` operationId: create_eval_run_evaluations_trace_runs_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateEvalRunRequest' responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/EvalRunResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] - ApiKey: [] - ProjectID: [] - ProjectName: [] components: schemas: CreateEvalRunRequest: properties: name: anyOf: - type: string - type: 'null' title: Name description: >- Optional human-readable label for this run (e.g. 'Weekly prod eval'). metrics: items: type: string type: array minItems: 1 title: Metrics description: >- List of metric names to run. Use GET /evaluations/trace-metrics to see available names. Example: ['task_completion', 'tool_correctness']. filters: $ref: '#/components/schemas/EvalRunFilters' description: >- Trace filters to select which traces to evaluate. Omit or leave empty to evaluate all traces in the project. sampling_rate: type: number maximum: 1 minimum: 0 title: Sampling Rate description: >- Fraction of matching traces to evaluate (0.0 to 1.0). 1.0 = all matching traces, 0.1 = random 10%. default: 1 model: anyOf: - type: string - type: 'null' title: Model description: >- LLM model string override for the judge (e.g. 'openai/gpt-4o'). Null uses the system default. type: object required: - metrics title: CreateEvalRunRequest description: >- Create a filtered eval run. The system resolves matching traces from the filters, optionally samples a fraction of them, then dispatches a background task to run the requested metrics asynchronously via an LLM judge. **Typical dashboard flow:** 1. User selects metrics -> call ``GET /trace-runs/template?metric=task_completion`` 2. Dashboard renders the template as a form with editable filters 3. User customizes filters/sampling -> frontend builds this request body 4. Frontend calls ``POST /trace-runs`` with the final body example: name: Weekly production eval metrics: - task_completion - tool_correctness - step_efficiency filters: date_from: '2026-03-22T00:00:00Z' date_to: '2026-03-29T00:00:00Z' status: COMPLETED sampling_rate: 0.5 model: gpt-5.4 EvalRunResponse: properties: id: type: string format: uuid title: Id name: anyOf: - type: string - type: 'null' title: Name status: $ref: '#/components/schemas/EvaluationStatus' metric_names: items: type: string type: array title: Metric Names total_traces: type: integer title: Total Traces evaluated_count: type: integer title: Evaluated Count failed_count: type: integer title: Failed Count created_at: type: string title: Created At completed_at: anyOf: - type: string - type: 'null' title: Completed At project_id: type: string format: uuid title: Project Id target_type: type: string title: Target Type filters: additionalProperties: true type: object title: Filters sampling_rate: type: number title: Sampling Rate model: anyOf: - type: string - type: 'null' title: Model monitor_id: anyOf: - type: string format: uuid - type: 'null' title: Monitor Id error_message: anyOf: - type: string - type: 'null' title: Error Message type: object required: - id - name - status - metric_names - total_traces - evaluated_count - failed_count - created_at - completed_at - project_id - target_type - filters - sampling_rate - model - monitor_id - error_message title: EvalRunResponse description: Full eval run representation used by both list and detail endpoints. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError EvalRunFilters: properties: date_from: anyOf: - type: string - type: 'null' title: Date From description: >- ISO 8601 datetime string (e.g. '2025-01-15T00:00:00Z'). Include traces started on or after this time. date_to: anyOf: - type: string - type: 'null' title: Date To description: >- ISO 8601 datetime string (e.g. '2025-02-01T00:00:00Z'). Include traces started before this time (exclusive). status: anyOf: - $ref: '#/components/schemas/TraceStatus' - type: 'null' description: 'Trace status: PENDING, RUNNING, COMPLETED, or ERROR.' session_id: anyOf: - type: string - type: 'null' title: Session Id description: Exact session ID string. Only traces belonging to this session. user_id: anyOf: - type: string - type: 'null' title: User Id description: Exact user ID string. Only traces from this user. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: >- List of tag strings (e.g. ['production', 'v2']). Traces matching ANY of these tags are included. name: anyOf: - type: string - type: 'null' title: Name description: >- Substring match on trace name (case-insensitive). E.g. 'booking' matches 'Flight Booking Agent'. type: object title: EvalRunFilters description: |- Trace filters for a filtered eval run. These mirror the GET /traces query parameters so the frontend can reuse the same filter UI components. EvaluationStatus: type: string enum: - PENDING - RUNNING - COMPLETED - FAILED title: EvaluationStatus description: Lifecycle status of an evaluation job. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError TraceStatus: type: string enum: - PENDING - RUNNING - COMPLETED - ERROR title: TraceStatus description: High-level status of a trace. securitySchemes: HTTPBearer: type: http scheme: bearer ApiKey: type: apiKey in: header name: X-API-Key ProjectID: type: apiKey in: header name: X-Project-ID ProjectName: type: apiKey in: header name: X-Project-Name ````