> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/legacy/legacy-experience/rest-api/v2/runs.md).

# Runs

Trigger and manage process runs. Start new runs and view details about run executions.

## List Runs

> Get a list of all the runs for a specified process and agent.

```json
{"openapi":"3.1.0","info":{"title":"Kognitos REST API v2","version":"2.0.0"},"tags":[{"description":"Trigger and manage process runs. Start new runs and view details about run executions.","name":"runs"}],"servers":[{"description":"US Region","url":"https://rest-api.app.kognitos.com/v2"},{"description":"EU Region","url":"https://rest-api.eu.kognitos.com/v2"},{"description":"UK Region","url":"https://rest-api.uk.kognitos.com/v2"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{"APIKeyHeader":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"ProcessStage":{"description":"Stage of a process","enum":["Draft","Published"],"title":"ProcessStage","type":"string"},"ListResponse":{"properties":{"continuation_token":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Used in subsequent GET requests to obtain more results for the same query (pagination)","title":"Continuation Token"},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"description":"List of resources","title":"Items"}},"required":["items","continuation_token"],"title":"ListResponse","type":"object"},"ErrorModel":{"properties":{"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/ErrorDetail"},"type":"array"},{"type":"null"}],"description":"An optional list of details about the error","title":"Details"},"message":{"description":"Error message","title":"Message","type":"string"},"status_code":{"description":"HTTP status code corresponding to the error","title":"Status Code","type":"integer"}},"required":["status_code","message"],"title":"ErrorModel","type":"object"},"ErrorDetail":{"properties":{"name":{"description":"Name of the error detail","title":"Name","type":"string"},"value":{"$ref":"#/components/schemas/ErrorDetailType","description":"Value of the error detail"}},"required":["name","value"],"title":"ErrorDetail","type":"object"},"ErrorDetailType":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}]}}},"paths":{"/runs":{"get":{"description":"Get a list of all the runs for a specified process and agent.","operationId":"list_runs","parameters":[{"description":"The unique identifier of the process.","in":"query","name":"process_id","required":true,"schema":{"description":"The unique identifier of the process.","title":"Process ID","type":"string"}},{"description":"The unique identifier of the agent.","in":"query","name":"agent_id","required":true,"schema":{"description":"The unique identifier of the agent.","title":"Agent ID","type":"string"}},{"description":"Maximum number of items to return.","in":"query","name":"limit","required":false,"schema":{"anyOf":[{"maximum":100,"type":"integer"},{"type":"null"}],"default":10,"description":"Maximum number of items to return.","title":"Limit"}},{"description":"The process stage.","in":"query","name":"stage","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ProcessStage"},{"type":"null"}],"description":"The process stage.","title":"Stage"}},{"description":"Pagination token used to retrieve the next page of results. It is returned in a prior response from a call made to this endpoint. ","in":"query","name":"continuation_token","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pagination token used to retrieve the next page of results. It is returned in a prior response from a call made to this endpoint. ","title":"Continuation Token"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListResponse"}}},"description":"A List of runs"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"Invalid input values"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"The specified process or agent was not found"}},"summary":"List Runs","tags":["runs"]}}}}
```

## Start a Run

> Initiates a new run (execution) of a specified process. Each run is an independent instance that can be tracked for status and results.

```json
{"openapi":"3.1.0","info":{"title":"Kognitos REST API v2","version":"2.0.0"},"tags":[{"description":"Trigger and manage process runs. Start new runs and view details about run executions.","name":"runs"}],"servers":[{"description":"US Region","url":"https://rest-api.app.kognitos.com/v2"},{"description":"EU Region","url":"https://rest-api.eu.kognitos.com/v2"},{"description":"UK Region","url":"https://rest-api.uk.kognitos.com/v2"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{"APIKeyHeader":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"CreateRunRequest":{"properties":{"agent_id":{"description":"The ID of the agent containing the process","maxLength":26,"minLength":1,"pattern":"^[a-zA-Z0-9-_]+$","title":"Agent Id","type":"string"},"file_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"List of IDs of files given as input to the process","title":"File Ids"},"inputs":{"anyOf":[{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array"},{"type":"null"}],"description":"Inputs to the process","title":"Inputs"},"name":{"description":"Name for this run","maxLength":100,"minLength":1,"title":"Name","type":"string"},"process_id":{"description":"The ID of the process to run","maxLength":26,"minLength":1,"pattern":"^[a-zA-Z0-9-_]+$","title":"Process Id","type":"string"},"stage":{"$ref":"#/components/schemas/ProcessStage","description":"The stage of the process"}},"required":["name","process_id","agent_id","stage"],"title":"CreateRunRequest","type":"object"},"RunInput":{"properties":{"name":{"description":"Name of the input parameter","maxLength":100,"minLength":1,"title":"Name","type":"string"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"Value of the input","title":"Value"}},"required":["name","value"],"title":"RunInput","type":"object"},"ProcessStage":{"description":"Stage of a process","enum":["Draft","Published"],"title":"ProcessStage","type":"string"},"RunResource":{"properties":{"agent_id":{"description":"The ID of the process's agent","maxLength":26,"minLength":1,"pattern":"^[a-zA-Z0-9-_]+$","title":"Agent Id","type":"string"},"created_at":{"description":"Date and time created","format":"date-time","title":"Created At","type":"string"},"file_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"List of IDs of files given as input to the process","title":"File Ids"},"id":{"description":"The ID of the resource","maxLength":26,"minLength":1,"pattern":"^[a-zA-Z0-9-_]+$","title":"Id","type":"string"},"name":{"description":"The name of the resource","maxLength":100,"minLength":1,"title":"Name","type":"string"},"outputs":{"anyOf":[{"items":{"$ref":"#/components/schemas/RunOutput"},"type":"array"},{"type":"null"}],"description":"Outputs of the process","title":"Outputs"},"process_id":{"description":"The ID of the process","maxLength":26,"minLength":1,"pattern":"^[a-zA-Z0-9-_]+$","title":"Process Id","type":"string"},"stage":{"$ref":"#/components/schemas/ProcessStage","description":"The stage of the process"},"status":{"$ref":"#/components/schemas/RunStatus","description":"Status of the run"}},"required":["agent_id","process_id","stage","status","created_at","id","name"],"title":"RunResource","type":"object"},"RunOutput":{"properties":{"name":{"description":"Name of the output result","maxLength":100,"minLength":1,"title":"Name","type":"string"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"Value of the output","title":"Value"}},"required":["name","value"],"title":"RunOutput","type":"object"},"RunStatus":{"description":"Status of a Run","enum":["Created","Running","Exception","Stopped","Succeeded"],"title":"RunStatus","type":"string"},"ErrorModel":{"properties":{"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/ErrorDetail"},"type":"array"},{"type":"null"}],"description":"An optional list of details about the error","title":"Details"},"message":{"description":"Error message","title":"Message","type":"string"},"status_code":{"description":"HTTP status code corresponding to the error","title":"Status Code","type":"integer"}},"required":["status_code","message"],"title":"ErrorModel","type":"object"},"ErrorDetail":{"properties":{"name":{"description":"Name of the error detail","title":"Name","type":"string"},"value":{"$ref":"#/components/schemas/ErrorDetailType","description":"Value of the error detail"}},"required":["name","value"],"title":"ErrorDetail","type":"object"},"ErrorDetailType":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}]}}},"paths":{"/runs":{"post":{"description":"Initiates a new run (execution) of a specified process. Each run is an independent instance that can be tracked for status and results.","operationId":"create_run","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRunRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResource"}}},"description":"The run created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"Invalid input values"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"A referenced resource was not found"}},"summary":"Start a Run","tags":["runs"]}}}}
```

## Get Run

> Get the details of a specific run.

```json
{"openapi":"3.1.0","info":{"title":"Kognitos REST API v2","version":"2.0.0"},"tags":[{"description":"Trigger and manage process runs. Start new runs and view details about run executions.","name":"runs"}],"servers":[{"description":"US Region","url":"https://rest-api.app.kognitos.com/v2"},{"description":"EU Region","url":"https://rest-api.eu.kognitos.com/v2"},{"description":"UK Region","url":"https://rest-api.uk.kognitos.com/v2"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{"APIKeyHeader":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"RunResource":{"properties":{"agent_id":{"description":"The ID of the process's agent","maxLength":26,"minLength":1,"pattern":"^[a-zA-Z0-9-_]+$","title":"Agent Id","type":"string"},"created_at":{"description":"Date and time created","format":"date-time","title":"Created At","type":"string"},"file_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"List of IDs of files given as input to the process","title":"File Ids"},"id":{"description":"The ID of the resource","maxLength":26,"minLength":1,"pattern":"^[a-zA-Z0-9-_]+$","title":"Id","type":"string"},"name":{"description":"The name of the resource","maxLength":100,"minLength":1,"title":"Name","type":"string"},"outputs":{"anyOf":[{"items":{"$ref":"#/components/schemas/RunOutput"},"type":"array"},{"type":"null"}],"description":"Outputs of the process","title":"Outputs"},"process_id":{"description":"The ID of the process","maxLength":26,"minLength":1,"pattern":"^[a-zA-Z0-9-_]+$","title":"Process Id","type":"string"},"stage":{"$ref":"#/components/schemas/ProcessStage","description":"The stage of the process"},"status":{"$ref":"#/components/schemas/RunStatus","description":"Status of the run"}},"required":["agent_id","process_id","stage","status","created_at","id","name"],"title":"RunResource","type":"object"},"RunOutput":{"properties":{"name":{"description":"Name of the output result","maxLength":100,"minLength":1,"title":"Name","type":"string"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"Value of the output","title":"Value"}},"required":["name","value"],"title":"RunOutput","type":"object"},"ProcessStage":{"description":"Stage of a process","enum":["Draft","Published"],"title":"ProcessStage","type":"string"},"RunStatus":{"description":"Status of a Run","enum":["Created","Running","Exception","Stopped","Succeeded"],"title":"RunStatus","type":"string"},"ErrorModel":{"properties":{"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/ErrorDetail"},"type":"array"},{"type":"null"}],"description":"An optional list of details about the error","title":"Details"},"message":{"description":"Error message","title":"Message","type":"string"},"status_code":{"description":"HTTP status code corresponding to the error","title":"Status Code","type":"integer"}},"required":["status_code","message"],"title":"ErrorModel","type":"object"},"ErrorDetail":{"properties":{"name":{"description":"Name of the error detail","title":"Name","type":"string"},"value":{"$ref":"#/components/schemas/ErrorDetailType","description":"Value of the error detail"}},"required":["name","value"],"title":"ErrorDetail","type":"object"},"ErrorDetailType":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}]}}},"paths":{"/runs/{run_id}":{"get":{"description":"Get the details of a specific run.","operationId":"get_run","parameters":[{"description":"The unique identifier of the run.","in":"path","name":"run_id","required":true,"schema":{"description":"The unique identifier of the run.","title":"Run ID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResource"}}},"description":"The requested run"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"Invalid input values"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"The specified run was not found"}},"summary":"Get Run","tags":["runs"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kognitos.com/legacy/legacy-experience/rest-api/v2/runs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.