> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/connect/n8n-api/evaluation.md).

# Evaluation

Operations about evaluation test runs

## Retrieve test runs

> Retrieve the evaluation test runs of a workflow.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Evaluation","description":"Operations about evaluation test runs"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"testRunWorkflowId":{"name":"id","in":"path","description":"The ID of the workflow.","required":true,"schema":{"type":"string"}},"limit":{"name":"limit","in":"query","description":"The maximum number of items to return.","required":false,"schema":{"type":"number","default":100,"maximum":250}},"cursor":{"name":"cursor","in":"query","description":"Paginate by setting the cursor parameter to the nextCursor attribute returned by the previous request's response. Default value fetches the first \"page\" of the collection. See pagination for more detail.","required":false,"style":"form","schema":{"type":"string"}}},"schemas":{"testRunList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/testRunSummary"}},"nextCursor":{"type":"string","nullable":true,"description":"Paginate through test runs by setting the cursor parameter to the nextCursor attribute returned by a previous request. Default value fetches the first \"page\" of the collection."}}},"testRunSummary":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["new","running","completed","error","cancelled"]},"runAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"metrics":{"type":"object","nullable":true,"additionalProperties":true,"description":"Aggregated metrics collected across the run's test cases."},"errorCode":{"type":"string","nullable":true},"errorDetails":{"type":"object","nullable":true,"additionalProperties":true},"finalResult":{"type":"string","nullable":true,"enum":["success","error","warning"],"description":"Overall result of the run, derived from its test cases once completed."},"testCaseCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/workflows/{id}/test-runs":{"get":{"tags":["Evaluation"],"summary":"Retrieve test runs","description":"Retrieve the evaluation test runs of a workflow.","parameters":[{"$ref":"#/components/parameters/testRunWorkflowId"},{"name":"status","in":"query","description":"Status to filter the test runs by.","required":false,"schema":{"type":"string","enum":["new","running","completed","error","cancelled"]}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/testRunList"}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## Trigger a test run

> Start a new evaluation test run for a workflow. The workflow must contain a configured evaluation trigger. Requires the \`workflow:execute\` project scope in addition to the \`testRun:create\` API key scope.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Evaluation","description":"Operations about evaluation test runs"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"testRunWorkflowId":{"name":"id","in":"path","description":"The ID of the workflow.","required":true,"schema":{"type":"string"}}},"schemas":{"testRun":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["new","running","completed","error","cancelled"]},"createdAt":{"type":"string","format":"date-time"}}}},"responses":{"unauthorized":{"description":"Unauthorized"},"paymentRequired":{"description":"Payment required"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"conflict":{"description":"Conflict"}}},"paths":{"/workflows/{id}/test-runs":{"post":{"tags":["Evaluation"],"summary":"Trigger a test run","description":"Start a new evaluation test run for a workflow. The workflow must contain a configured evaluation trigger. Requires the `workflow:execute` project scope in addition to the `testRun:create` API key scope.","parameters":[{"$ref":"#/components/parameters/testRunWorkflowId"}],"responses":{"201":{"description":"Test run triggered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/testRun"}}}},"401":{"$ref":"#/components/responses/unauthorized"},"402":{"$ref":"#/components/responses/paymentRequired"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/conflict"}}}}}}
```

## Retrieve a test run

> Retrieve a single evaluation test run of a workflow, including its aggregated metrics and final result.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Evaluation","description":"Operations about evaluation test runs"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"testRunWorkflowId":{"name":"id","in":"path","description":"The ID of the workflow.","required":true,"schema":{"type":"string"}},"testRunId":{"name":"runId","in":"path","description":"The ID of the test run.","required":true,"schema":{"type":"string"}}},"schemas":{"testRunSummary":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["new","running","completed","error","cancelled"]},"runAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"metrics":{"type":"object","nullable":true,"additionalProperties":true,"description":"Aggregated metrics collected across the run's test cases."},"errorCode":{"type":"string","nullable":true},"errorDetails":{"type":"object","nullable":true,"additionalProperties":true},"finalResult":{"type":"string","nullable":true,"enum":["success","error","warning"],"description":"Overall result of the run, derived from its test cases once completed."},"testCaseCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/workflows/{id}/test-runs/{runId}":{"get":{"tags":["Evaluation"],"summary":"Retrieve a test run","description":"Retrieve a single evaluation test run of a workflow, including its aggregated metrics and final result.","parameters":[{"$ref":"#/components/parameters/testRunWorkflowId"},{"$ref":"#/components/parameters/testRunId"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/testRunSummary"}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## Cancel a test run

> Cancel a running evaluation test run of a workflow. Requires the \`workflow:execute\` project scope in addition to the \`testRun:cancel\` API key scope.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Evaluation","description":"Operations about evaluation test runs"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"testRunWorkflowId":{"name":"id","in":"path","description":"The ID of the workflow.","required":true,"schema":{"type":"string"}},"testRunId":{"name":"runId","in":"path","description":"The ID of the test run.","required":true,"schema":{"type":"string"}}},"schemas":{"testRunCancel":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["cancelled"]}}}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"conflict":{"description":"Conflict"}}},"paths":{"/workflows/{id}/test-runs/{runId}/cancel":{"post":{"tags":["Evaluation"],"summary":"Cancel a test run","description":"Cancel a running evaluation test run of a workflow. Requires the `workflow:execute` project scope in addition to the `testRun:cancel` API key scope.","parameters":[{"$ref":"#/components/parameters/testRunWorkflowId"},{"$ref":"#/components/parameters/testRunId"}],"responses":{"202":{"description":"Cancellation requested.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/testRunCancel"}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/conflict"}}}}}}
```

## Retrieve test run cases

> Retrieve the per-case results of an evaluation test run.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Evaluation","description":"Operations about evaluation test runs"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"testRunWorkflowId":{"name":"id","in":"path","description":"The ID of the workflow.","required":true,"schema":{"type":"string"}},"testRunId":{"name":"runId","in":"path","description":"The ID of the test run.","required":true,"schema":{"type":"string"}},"limit":{"name":"limit","in":"query","description":"The maximum number of items to return.","required":false,"schema":{"type":"number","default":100,"maximum":250}},"cursor":{"name":"cursor","in":"query","description":"Paginate by setting the cursor parameter to the nextCursor attribute returned by the previous request's response. Default value fetches the first \"page\" of the collection. See pagination for more detail.","required":false,"style":"form","schema":{"type":"string"}}},"schemas":{"testCaseExecutionList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/testCaseExecution"}},"nextCursor":{"type":"string","nullable":true,"description":"Paginate through test cases by setting the cursor parameter to the nextCursor attribute returned by a previous request. Default value fetches the first \"page\" of the collection."}}},"testCaseExecution":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["new","running","evaluation_running","success","error","warning","cancelled"]},"runAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"metrics":{"type":"object","nullable":true,"additionalProperties":true,"description":"Metrics produced by this test case."},"errorCode":{"type":"string","nullable":true},"errorDetails":{"type":"object","nullable":true,"additionalProperties":true},"inputs":{"type":"object","nullable":true,"additionalProperties":true,"description":"Input data for this test case."},"outputs":{"type":"object","nullable":true,"additionalProperties":true,"description":"Output data produced by this test case."},"executionId":{"type":"string","nullable":true,"description":"ID of the underlying workflow execution, if still retained."}}}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/workflows/{id}/test-runs/{runId}/test-cases":{"get":{"tags":["Evaluation"],"summary":"Retrieve test run cases","description":"Retrieve the per-case results of an evaluation test run.","parameters":[{"$ref":"#/components/parameters/testRunWorkflowId"},{"$ref":"#/components/parameters/testRunId"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/testCaseExecutionList"}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```