> 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":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"parameters":{"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"}}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/workflows/{workflowId}/test-runs":{"get":{"operationId":"getTestRuns","tags":["Evaluation"],"summary":"Retrieve test runs","description":"Retrieve the evaluation test runs of a workflow.","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"schema":{"type":"string"},"required":true,"description":"The ID of the workflow.","name":"workflowId","in":"path"},{"schema":{"type":"string","enum":["new","running","completed","error","cancelled"],"description":"Status to filter the test runs by."},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["new","running","completed","error","cancelled"]},"runAt":{"type":"string","nullable":true,"format":"date-time"},"completedAt":{"type":"string","nullable":true,"format":"date-time"},"metrics":{"type":"object","description":"Aggregated metrics collected across the run's test cases.","additionalProperties":true,"nullable":true},"errorCode":{"type":"string","nullable":true},"errorDetails":{"type":"object","additionalProperties":true,"nullable":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"}},"required":["id","status","runAt","completedAt","metrics","errorCode","errorDetails","finalResult","testCaseCount","createdAt","updatedAt"]}},"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."}},"required":["data","nextCursor"]}}}},"400":{"$ref":"#/components/responses/badRequest"},"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":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"responses":{"unauthorized":{"description":"Unauthorized"},"paymentRequired":{"description":"Payment required"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"conflict":{"description":"Conflict"}}},"paths":{"/workflows/{workflowId}/test-runs":{"post":{"operationId":"createTestRun","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":[{"schema":{"type":"string"},"required":true,"description":"The ID of the workflow.","name":"workflowId","in":"path"}],"responses":{"201":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["new","running","completed","error","cancelled"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","status","createdAt"]}}}},"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":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/workflows/{workflowId}/test-runs/{runId}":{"get":{"operationId":"getTestRun","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":[{"schema":{"type":"string"},"required":true,"description":"The ID of the workflow.","name":"workflowId","in":"path"},{"schema":{"type":"string"},"required":true,"description":"The ID of the test run.","name":"runId","in":"path"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["new","running","completed","error","cancelled"]},"runAt":{"type":"string","nullable":true,"format":"date-time"},"completedAt":{"type":"string","nullable":true,"format":"date-time"},"metrics":{"type":"object","description":"Aggregated metrics collected across the run's test cases.","additionalProperties":true,"nullable":true},"errorCode":{"type":"string","nullable":true},"errorDetails":{"type":"object","additionalProperties":true,"nullable":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"}},"required":["id","status","runAt","completedAt","metrics","errorCode","errorDetails","finalResult","testCaseCount","createdAt","updatedAt"]}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## 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":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"parameters":{"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"}}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/workflows/{workflowId}/test-runs/{runId}/test-cases":{"get":{"operationId":"getTestCases","tags":["Evaluation"],"summary":"Retrieve test run cases","description":"Retrieve the per-case results of an evaluation test run.","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"schema":{"type":"string"},"required":true,"description":"The ID of the workflow.","name":"workflowId","in":"path"},{"schema":{"type":"string"},"required":true,"description":"The ID of the test run.","name":"runId","in":"path"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["new","running","evaluation_running","success","error","warning","cancelled"]},"runAt":{"type":"string","nullable":true,"format":"date-time"},"completedAt":{"type":"string","nullable":true,"format":"date-time"},"metrics":{"type":"object","description":"Metrics produced by this test case.","additionalProperties":true,"nullable":true},"errorCode":{"type":"string","nullable":true},"errorDetails":{"type":"object","additionalProperties":true,"nullable":true},"inputs":{"type":"object","description":"Input data for this test case.","additionalProperties":true,"nullable":true},"outputs":{"type":"object","description":"Output data produced by this test case.","additionalProperties":true,"nullable":true},"executionId":{"type":"integer","nullable":true,"description":"ID of the underlying workflow execution, if still retained."}},"required":["id","status","runAt","completedAt","metrics","errorCode","errorDetails","inputs","outputs","executionId"]}},"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."}},"required":["data","nextCursor"]}}}},"400":{"$ref":"#/components/responses/badRequest"},"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":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"conflict":{"description":"Conflict"}}},"paths":{"/workflows/{workflowId}/test-runs/{runId}/cancel":{"post":{"operationId":"cancelTestRun","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":[{"schema":{"type":"string"},"required":true,"description":"The ID of the workflow.","name":"workflowId","in":"path"},{"schema":{"type":"string"},"required":true,"description":"The ID of the test run.","name":"runId","in":"path"}],"responses":{"202":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["cancelled"]}},"required":["id","status"]}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/conflict"}}}}}}
```