--- title: "Retrieve Test Run" method: GET path: "/v1/test-runs/{testRunId}" tags: ["Evaluation"] --- # Retrieve Test Run `GET /v1/test-runs/{testRunId}` ## Request - Base URL: `https://api.confident-ai.com` - URL: `https://api.confident-ai.com/v1/test-runs/{testRunId}` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Retrieves a list of test cases and their respective metrics from a test run. ## Response `200` - TestRunResponse - `success` boolean, required: This is true if the test run was successfully retrieved. - `data` object, required - `metricsScores` MetricScores[], required: The aggregated metric scores across all test cases. - `fails` number, required: This is the number of times this metric failed to pass the threshold. - `errors` number, required: This is the number of times this metric errored during evaluation. - `metric` string, required: This is the name of the metric. - `passes` number, required: This is the number of times this metric passed the threshold. - `scores` number[], required: This is an array of scores for the metric across test cases. - `testCases` union[], required: The test cases in this test run. Will contain either single-turn test cases or conversational test cases, but not both. - union - TestRunTestCase - `id` string, required: This is the id of the test case generated by Confident AI. - `name` string, required: This is the name of the test case. - `input` string, required: This is the input of the test case. - `actualOutput` string: This is the actual output of the test case. - `context` string[]: This is the context of the test case. - `retrievalContext` string[]: This is the retrieval context of the test case. - `expectedOutput` string: This is the expected output of the test case. - `toolsCalled` ToolCallData[]: This is the tools called of the test case. - `name` string, required: This is the name of the tool. - `description` string, required: This is the description of the tool. - `inputParameters` object: This is the input parameters that are passed to the tool. - `output` string: This is the output of the tool. - `reasoning` string: This is the reasoning your LLM provided for the tool call. - `expectedTools` ToolCallData[]: This is the expected tools of the test case. - `name` string, required: This is the name of the tool. - `description` string, required: This is the description of the tool. - `inputParameters` object: This is the input parameters that are passed to the tool. - `output` string: This is the output of the tool. - `reasoning` string: This is the reasoning your LLM provided for the tool call. - `metricsData` MetricsData[]: The metric evaluation results for this test case. - `id` string, required: The unique identifier of the metrics data entry. - `projectId` string, required: The project this metric data belongs to. - `traceUuid` string, nullable: The UUID of the trace this metric data is associated with, if any. - `spanUuid` string, nullable: The UUID of the span this metric data is associated with, if any. - `testCaseId` string, nullable: The ID of the test case this metric data is associated with, if any. - `testRunId` string, nullable: The ID of the test run this metric data is associated with, if any. - `threadId` string, nullable: The ID of the thread this metric data is associated with, if any. - `name` string, required: The name of the metric. - `multiTurn` boolean, required: Whether this metric was evaluated on a multi-turn conversation. - `score` number, nullable: The final metric score. - `reason` string, nullable: The reason for the metric score, generated by the evaluation model at evaluation time. - `success` boolean, nullable: Whether the metric score is above the threshold. - `createdAt` string, date-time, required: The time the metric data was created. - `evaluatedAt` string, date-time, nullable: The time the metric was evaluated. - `threshold` number, float, required: The threshold for the metric, which determines if the metric is passing or failing. - `strictMode` boolean, required: Whether the metric was run in strict mode, which outputs a binary score of 0 or 1. - `skipped` boolean, required: Whether the metric evaluation was skipped. - `evaluationModel` string, nullable: The evaluation model used to run the evaluation. - `error` string, nullable: The error message if the evaluation failed. - `evaluationCost` number, float, nullable: The cost of running the evaluation. - `verboseLogs` string, nullable: The verbose logs of the evaluation, which breaks down the metric score calculation into individual steps. - `comments` string: Any comments associated with this test case. - `additionalMetadata` object: Additional metadata associated with this test case. - `success` boolean: Whether this test case passed all metric thresholds. - `runDuration` number, float: The duration of the test case evaluation in seconds. - `evaluationCost` number, float: The cost of evaluating this test case. - `trace` Trace - `uuid` string, required: This is the unique identifier of the trace. - `name` string: This is the name of the trace. - `input` string: This is the input to the trace. - `output` string: This is the output of the trace. - `startTime` string, date-time, required: This is the time the trace started. - `endTime` string, date-time, required: This is the time the trace ended. - `environment` 'production' | 'development' | 'staging' | 'testing': This is the environment where your trace was posted, which helps with separating and debugging traces from different environments on the Confident AI platform. - `metadata` object: This is any additional metadata associated with the trace. - `tags` string[]: This is any tags associated with the trace, which helps with grouping traces and filtering them on the Confident AI platform. - `spans` union[]: This is the list of base spans associated with the trace. - … - `threadId` string: This is the unique identifier of the thread associated with the trace. - `thread` object: Thread-level fields applied to the thread record. `thread.id` is an alternate way to specify the thread (must match top-level `threadId` if both are provided). `metadata` and `tags` only take effect when a thread id is resolvable; successive ingestions merge metadata keys, while tags replace any prior value. - … - `userId` string: This is the unique identifier for your end user for the trace. - `metricCollection` string: This is the metric collection you wish to use to evaluate the trace. - `testRunId` string: This is the unique identifier of the test run to associate the trace with. When set, the trace becomes one test case in that test run, and `metricCollection` is required. Create a test run with the `POST /v1/test-runs` endpoint to get this id. - `retrievalContext` string[]: This is the retrieval context of your trace, which is to be used for evaluation. - `context` string[]: This is the ideal retrieval context of your trace, which is to be used for evaluation. - `expectedOutput` string: This is the expected output of your trace, which is the ideal actual output and to be used for evaluation. - `toolsCalled` ToolCallData[]: This is the tools called by your trace, which is to be used for evaluation. - … - `expectedTools` ToolCallData[]: This is the expected tools to be called by the trace, which is to be used for evaluation. - … - `attachments` object: Map of attachment ids to payloads for all `[DEEPEVAL:IMAGE:…]` and `[DEEPEVAL:PDF:…]` markers in this trace. Define attachments at the trace level with same ids for same instances. - TestRunConversationalTestCase - `id` string, required: This is the id of the conversational test case generated by Confident AI. - `name` string, required: This is the name of the conversational test case. - `turns` TestRunTurn[], required: The list of turns in the conversation. - `role` 'user' | 'assistant', required: The role of the turn, either user or assistant. - `content` string, required: The message content of the turn. - `toolsCalled` ToolCallData[]: The tools called to generate the LLM response for this turn. - … - `retrievalContext` string[]: The contexts retrieved to generate the LLM response for this turn. - `scenario` string: A description of the conversation context. - `expectedOutcome` string: The expected outcome or ideal conversation flow. - `userDescription` string: A description of the user in the conversation. - `context` string[]: The context provided for the conversation. - `comments` string: Any comments associated with this test case. - `additionalMetadata` object: Additional metadata associated with this test case. - `metricsData` MetricsData[]: The metric evaluation results for this test case. - `id` string, required: The unique identifier of the metrics data entry. - `projectId` string, required: The project this metric data belongs to. - `traceUuid` string, nullable: The UUID of the trace this metric data is associated with, if any. - `spanUuid` string, nullable: The UUID of the span this metric data is associated with, if any. - `testCaseId` string, nullable: The ID of the test case this metric data is associated with, if any. - `testRunId` string, nullable: The ID of the test run this metric data is associated with, if any. - `threadId` string, nullable: The ID of the thread this metric data is associated with, if any. - `name` string, required: The name of the metric. - `multiTurn` boolean, required: Whether this metric was evaluated on a multi-turn conversation. - `score` number, nullable: The final metric score. - `reason` string, nullable: The reason for the metric score, generated by the evaluation model at evaluation time. - `success` boolean, nullable: Whether the metric score is above the threshold. - `createdAt` string, date-time, required: The time the metric data was created. - `evaluatedAt` string, date-time, nullable: The time the metric was evaluated. - `threshold` number, float, required: The threshold for the metric, which determines if the metric is passing or failing. - `strictMode` boolean, required: Whether the metric was run in strict mode, which outputs a binary score of 0 or 1. - `skipped` boolean, required: Whether the metric evaluation was skipped. - `evaluationModel` string, nullable: The evaluation model used to run the evaluation. - `error` string, nullable: The error message if the evaluation failed. - `evaluationCost` number, float, nullable: The cost of running the evaluation. - `verboseLogs` string, nullable: The verbose logs of the evaluation, which breaks down the metric score calculation into individual steps. - `success` boolean: Whether this test case passed all metric thresholds. - `runDuration` number, float: The duration of the test case evaluation in seconds. - `evaluationCost` number, float: The cost of evaluating this test case. - `multiTurn` boolean: Whether this test run contains multi-turn test cases. - `identifier` string: A unique identifier for the test run. - `status` 'IN_PROGRESS' | 'COMPLETED' | 'ERRORED' | 'CANCELLED': The current status of the test run. - `testsPassed` number: The number of test cases that passed. - `testsFailed` number: The number of test cases that failed. - `totalTests` number: The total number of test cases in this test run. - `runDuration` number, float: The total duration of the test run in seconds. - `deprecated` boolean, required: This is true if this endpoint is deprecated. ## Changes > 54 revisions in range; 3 not diffed. - **2026-06-30** `448829180950`: 1 info - added the optional property `data/testCases/items/oneOf[subschema #1: LLMTestCase]/trace/testRunId` to the response with the `200` status - **2026-06-29** `77c4156f18d2`: 1 warning - removed the optional property `data/testCases/items/oneOf[subschema #1: LLMTestCase]/trace/testRunId` from the response with the `200` status - **2026-06-29** `c77c54067665`: 1 info - added the optional property `data/testCases/items/oneOf[subschema #1: LLMTestCase]/trace/testRunId` to the response with the `200` status - **2026-06-28** `0d196a3b614e`: 1 warning - removed the optional property `data/testCases/items/oneOf[subschema #1: LLMTestCase]/trace/testRunId` from the response with the `200` status - **2026-06-28** `c1fef814439e`: 1 info - added the optional property `data/testCases/items/oneOf[subschema #1: LLMTestCase]/trace/testRunId` to the response with the `200` status [Operation history](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/changes/v1/test-runs/:testRunId/get.md) --- [API](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api.md) - [All operations](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/revisions/95cdde71b65e?raw)