> For the complete documentation index, see [llms.txt](https://docs.frends.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.frends.com/reference/frends-platform-api/platform-api-reference/process-instances.md).

# Process Instances

## GET /api/v1/instances/{agentGroupId}

> List Process Instances

```json
{"openapi":"3.1.1","info":{"title":"Frends API","version":"1.0.0"},"tags":[{"name":"ProcessInstances"}],"servers":[{"url":"https://example.v64.frendsapp.com/"}],"security":[{}],"paths":{"/api/v1/instances/{agentGroupId}":{"get":{"tags":["ProcessInstances"],"summary":"List Process Instances","operationId":"ListInstances","parameters":[{"name":"agentGroupId","in":"path","description":"Agent Group where Process Instances should be fetched from","required":true,"schema":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":"integer","format":"int64"}},{"name":"processGuids","in":"query","description":"Filter by Processes","schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"startTime","in":"query","description":"Filter by Execution start time","schema":{"type":"string","format":"date-time"}},{"name":"endTime","in":"query","description":"Filter by Execution end time","schema":{"type":"string","format":"date-time"}},{"name":"stateFilter","in":"query","description":"Filter by Execution state","schema":{"$ref":"#/components/schemas/ProcessInstanceFilter"}},{"name":"isChildProcess","in":"query","description":"Filter by whether process is a child process (i.e. a subprocess, if not started manually)","schema":{"type":"boolean"}},{"name":"continuationToken","in":"query","description":"If there are more results to be shown a continuationToken will be needed to show the next set of results. This token is passed as nextContinuationToken in the result of the previous query. <b>Warning! If any filters except continuationToken are changed between requests the results will be invalid</b>","schema":{"type":"string"}},{"name":"pageSize","in":"query","description":"Maximum page size is 200. Default page size is 50","schema":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32","default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DtoProcessInstanceGet"}}}},"404":{"description":"Not Found","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"ProcessInstanceFilter":{"enum":["ShowAll","ShowRunning","ShowFinished","ShowSuccessful","ShowFailed","ShowFailedNotAcknowledged",null]},"DtoProcessInstanceGet":{"type":"object","properties":{"nextContinuationToken":{"type":["null","string"],"description":"ContinuationToken to be used in the next query. Warning! If any filters except continuationToken are changed between requests the results will be invalid. If the token is null there are no more results to fetch with the selected filters."},"nextLink":{"oneOf":[{"type":"null"},{"description":"Link for next set of results with the same query filters","$ref":"#/components/schemas/LinkModel"}]},"data":{"type":["null","array"],"items":{"$ref":"#/components/schemas/ProcessInstanceViewModel"},"description":"Response data"}}},"LinkModel":{"required":["uri","method"],"type":"object","properties":{"uri":{"type":"string","format":"uri"},"method":{"type":"string"}}},"ProcessInstanceViewModel":{"type":"object","properties":{"triggerName":{"type":["null","string"]},"environmentName":{"type":["null","string"]},"agentGroupName":{"type":["null","string"]},"agentName":{"type":["null","string"]},"processGuid":{"type":"string","format":"uuid"},"parentName":{"type":["null","string"]},"triggerRequest":{"type":["null","array"],"items":{"type":"array","items":{"type":"array","items":{}}}},"triggerResponses":{"type":["null","array"],"items":{"type":"array","items":{}}},"promotedColumns":{"type":["null","array"],"items":{"$ref":"#/components/schemas/PromotedColumn"}},"dehydrationState":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DehydrationState"}]},"correlationId":{"type":["null","string"]},"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int64"},"parentId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int64"},"processId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"rootProcessId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"processVersion":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"state":{"$ref":"#/components/schemas/ExecutionState"},"startTimeUtc":{"type":["null","string"],"format":"date-time"},"endTimeUtc":{"type":["null","string"],"format":"date-time"},"utcDate":{"type":"string","format":"date-time"},"utcHour":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int16"},"executionId":{"type":"string","format":"uuid"},"triggerId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"agentId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"environmentId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"agentGroupId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"exception":{"type":["null","string"]},"userName":{"type":["null","string"]},"hasLoggedSteps":{"type":["null","boolean"]},"acknowledgedUtc":{"type":["null","string"],"format":"date-time"},"commentJson":{"type":["null","string"]},"comment":{"type":"string"},"promotedData":{"type":["null","array"],"items":{"$ref":"#/components/schemas/ProcessPromotedData"}}}},"PromotedColumn":{"type":"object","properties":{"name":{"type":["null","string"]},"value":{"type":["null","array"],"items":{"type":"array","items":{}}}}},"DehydrationState":{"enum":["Dehydrated","Hydrated","DehydrationProcessFailure",null]},"ExecutionState":{"enum":["Ok","Waiting","Launched","Starting","Started","Canceled","CanceledByTerminate","FinishedAsZombie","TerminatedByUser","ActionSkipped","Failed","Exception","Finished"]},"ProcessPromotedData":{"required":["environmentName","promotedVariableName","promotedValueJson"],"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int64"},"processExecutionId":{"type":"string","format":"uuid"},"timeStamp":{"type":"string","format":"date-time"},"environmentName":{"type":"string"},"promotedVariableName":{"type":"string"},"promotedValueJson":{"type":"string"}}}}}}
```

## GET /api/v1/instances/{agentGroupId}/{executionIdentifier}/details

> Get Process Instance Details

```json
{"openapi":"3.1.1","info":{"title":"Frends API","version":"1.0.0"},"tags":[{"name":"ProcessInstances"}],"servers":[{"url":"https://example.v64.frendsapp.com/"}],"security":[{}],"paths":{"/api/v1/instances/{agentGroupId}/{executionIdentifier}/details":{"get":{"tags":["ProcessInstances"],"summary":"Get Process Instance Details","parameters":[{"name":"agentGroupId","in":"path","description":"Agent Group where Process Instance should be fetched from","required":true,"schema":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":"integer","format":"int64"}},{"name":"executionIdentifier","in":"path","description":"Execution identifier of the Process Instance","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseOfProcessInstanceExecutionDetailsViewModel"}}}},"404":{"description":"Not Found","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"ResponseOfProcessInstanceExecutionDetailsViewModel":{"required":["data"],"type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"description":"Response data","$ref":"#/components/schemas/ProcessInstanceExecutionDetailsViewModel"}]}}},"ProcessInstanceExecutionDetailsViewModel":{"required":["parentName","processGuid","rootProcessGuid","environment","agentGroup","agent","userName","triggerName","processParameters","processReturnValues"],"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int64"},"parentId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int64"},"parentName":{"type":"string"},"executionId":{"type":"string","format":"uuid"},"processGuid":{"type":"string","format":"uuid"},"rootProcessGuid":{"type":["null","string"],"format":"uuid"},"processVersion":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"state":{"$ref":"#/components/schemas/ExecutionState"},"dehydrationState":{"$ref":"#/components/schemas/DehydrationState"},"stepDataUri":{"type":["null","string"]},"startTimeUtc":{"type":["null","string"],"format":"date-time"},"endTimeUtc":{"type":["null","string"],"format":"date-time"},"duration":{"pattern":"^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$","type":["null","string"]},"environment":{"type":"string"},"agentGroup":{"type":"string"},"agent":{"type":"string"},"exception":{"type":["null","string"]},"userName":{"type":"string"},"triggerName":{"type":"string"},"processParameters":{"type":["null","array"],"items":{"type":"array","items":{"type":"array","items":{}}}},"processReturnValues":{"type":["null","array"],"items":{"type":"array","items":{}}},"hasLoggedSteps":{"type":["null","boolean"]},"correlationId":{"type":["null","string"]}}},"ExecutionState":{"enum":["Ok","Waiting","Launched","Starting","Started","Canceled","CanceledByTerminate","FinishedAsZombie","TerminatedByUser","ActionSkipped","Failed","Exception","Finished"]},"DehydrationState":{"enum":["Dehydrated","Hydrated","DehydrationProcessFailure",null]}}}}
```

## GET /api/v1/instances/counts/{agentGroupId}

> Returns Process instance counts

```json
{"openapi":"3.1.1","info":{"title":"Frends API","version":"1.0.0"},"tags":[{"name":"ProcessInstances"}],"servers":[{"url":"https://example.v64.frendsapp.com/"}],"security":[{}],"paths":{"/api/v1/instances/counts/{agentGroupId}":{"get":{"tags":["ProcessInstances"],"summary":"Returns Process instance counts","parameters":[{"name":"agentGroupId","in":"path","required":true,"schema":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":"integer","format":"int64"}},{"name":"ProcessUniqueIdentifiers","in":"query","description":"The unique identifiers of the Processes to get the counts for.","schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"StartTime","in":"query","description":"The start time of the execution of the Processes to get the counts for.","schema":{"type":"string","format":"date-time"}},{"name":"EndTime","in":"query","description":"The end time of the execution of the Processes to get the counts for.","schema":{"type":"string","format":"date-time"}},{"name":"GroupedHourly","in":"query","description":"Groups counts by hour instead of by date.","schema":{"type":"boolean"}},{"name":"CountsTimeLimitDays","in":"query","description":"Limit counts by days","schema":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseOfProcessCountsByAgentGroupAndProcessAndDateTime"}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"ResponseOfProcessCountsByAgentGroupAndProcessAndDateTime":{"required":["data"],"type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"description":"Response data","$ref":"#/components/schemas/ProcessCountsByAgentGroupAndProcessAndDateTime"}]}}},"ProcessCountsByAgentGroupAndProcessAndDateTime":{"required":["executionCounts"],"type":"object","properties":{"executionCounts":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ProcessInstanceExecutionCounts"}}}}}},"ProcessInstanceExecutionCounts":{"type":"object","properties":{"running":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"latestRunning":{"type":["null","string"],"format":"date-time"},"successful":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"latestSuccessful":{"type":["null","string"],"format":"date-time"},"failed":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"latestFailed":{"type":["null","string"],"format":"date-time"},"erroredNotAcknowledged":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"latestExecutionState":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ExecutionState"}]}}},"ExecutionState":{"enum":["Ok","Waiting","Launched","Starting","Started","Canceled","CanceledByTerminate","FinishedAsZombie","TerminatedByUser","ActionSkipped","Failed","Exception","Finished"]},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}}}}}}
```

## POST /api/v1/instances/{agentGroupId}/{processGuid}/acknowledge

> Acknowledges errors of specified instances of the specified Process in the specified Agent Group.

```json
{"openapi":"3.1.1","info":{"title":"Frends API","version":"1.0.0"},"tags":[{"name":"ProcessInstances"}],"servers":[{"url":"https://example.v64.frendsapp.com/"}],"security":[{}],"paths":{"/api/v1/instances/{agentGroupId}/{processGuid}/acknowledge":{"post":{"tags":["ProcessInstances"],"summary":"Acknowledges errors of specified instances of the specified Process in the specified Agent Group.","parameters":[{"name":"agentGroupId","in":"path","required":true,"schema":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":"integer","format":"int64"}},{"name":"processGuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"Model of the request to acknowledge Process instance errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcknowledgeInstanceErrorsQueryModel"}}},"required":true},"responses":{"204":{"description":"No Content"},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"AcknowledgeInstanceErrorsQueryModel":{"required":["reason","instanceIds"],"type":"object","properties":{"reason":{"type":"string"},"instanceIds":{"type":"array","items":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int64"}}}},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}}}}}}
```

## POST /api/v1/instances/{agentGroupId}/{processGuid}/comment

> Comments specified Process instances in the Agent Group.

```json
{"openapi":"3.1.1","info":{"title":"Frends API","version":"1.0.0"},"tags":[{"name":"ProcessInstances"}],"servers":[{"url":"https://example.v64.frendsapp.com/"}],"security":[{}],"paths":{"/api/v1/instances/{agentGroupId}/{processGuid}/comment":{"post":{"tags":["ProcessInstances"],"summary":"Comments specified Process instances in the Agent Group.","parameters":[{"name":"agentGroupId","in":"path","required":true,"schema":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":"integer","format":"int64"}},{"name":"processGuid","in":"path","description":"GUID of the Process.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"Model of the request to comment Process instances.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentInstancesQueryModel"}}},"required":true},"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"CommentInstancesQueryModel":{"required":["comment","instanceIds"],"type":"object","properties":{"comment":{"type":"string"},"processGuids":{"type":["null","array"],"items":{"type":"string","format":"uuid"}},"instanceIds":{"type":"array","items":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int64"}}}},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}}}}}}
```

## GET /api/v1/instances/{agentGroupId}/{processGuid}/export

> Downloads CSV-exported data of Process instances of a specified Process in a specified Agent Group, from a specified timespan.

```json
{"openapi":"3.1.1","info":{"title":"Frends API","version":"1.0.0"},"tags":[{"name":"ProcessInstances"}],"servers":[{"url":"https://example.v64.frendsapp.com/"}],"security":[{}],"paths":{"/api/v1/instances/{agentGroupId}/{processGuid}/export":{"get":{"tags":["ProcessInstances"],"summary":"Downloads CSV-exported data of Process instances of a specified Process in a specified Agent Group, from a specified timespan.","parameters":[{"name":"agentGroupId","in":"path","required":true,"schema":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":"integer","format":"int64"}},{"name":"processGuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"startTime","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"endTime","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"instanceIds","in":"query","description":"IDs of the Process instances. If unspecified, the operation will return 10000 instances.","schema":{"type":"array","items":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int64"}}}],"responses":{"200":{"description":"OK","content":{"text/csv":{"schema":{"$ref":"#/components/schemas/FileContentResult"}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"FileContentResult":{"type":"object","properties":{"fileContents":{"type":"string","format":"byte"},"contentType":{"type":["null","string"]},"fileDownloadName":{"type":["null","string"]},"lastModified":{"type":["null","string"],"format":"date-time"},"entityTag":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/EntityTagHeaderValue"}]},"enableRangeProcessing":{"type":"boolean"}}},"EntityTagHeaderValue":{"type":"object","properties":{"tag":{"$ref":"#/components/schemas/StringSegment"},"isWeak":{"type":"boolean"}}},"StringSegment":{"type":"object","properties":{"buffer":{"type":["null","string"]},"offset":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"length":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"value":{"type":["null","string"]},"hasValue":{"type":"boolean"}}},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}}}}}}
```

## POST /api/v1/instances/{agentGroupId}/{processGuid}/delete

> Deletes Process instances of a specified Process in a specified Agent Group.

```json
{"openapi":"3.1.1","info":{"title":"Frends API","version":"1.0.0"},"tags":[{"name":"ProcessInstances"}],"servers":[{"url":"https://example.v64.frendsapp.com/"}],"security":[{}],"paths":{"/api/v1/instances/{agentGroupId}/{processGuid}/delete":{"post":{"tags":["ProcessInstances"],"summary":"Deletes Process instances of a specified Process in a specified Agent Group.","parameters":[{"name":"agentGroupId","in":"path","required":true,"schema":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":"integer","format":"int64"}},{"name":"processGuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"Array of Process instance identifiers.","content":{"application/json":{"schema":{"type":"array","items":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int64"}}}},"required":true},"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}}}}}}
```


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.frends.com/reference/frends-platform-api/platform-api-reference/process-instances.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
