Runs
Get run detail (with steps, human-step status and outputs)
Get run detail (with steps, human-step status and outputs). Requires permission runs:read.
GET
/
api
/
v3
/
runs
/
{runId}
Get run detail (with steps, human-step status and outputs)
curl --request GET \
--url https://api.forge.gloo.com/api/v3/runs/{runId} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.forge.gloo.com/api/v3/runs/{runId}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.forge.gloo.com/api/v3/runs/{runId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.forge.gloo.com/api/v3/runs/{runId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.forge.gloo.com/api/v3/runs/{runId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.forge.gloo.com/api/v3/runs/{runId}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.forge.gloo.com/api/v3/runs/{runId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": {
"id": "<string>",
"runType": "<string>",
"status": "<string>",
"interfaceId": "<string>",
"workflowId": "<string>",
"workflowVersion": 123,
"goal": "<string>",
"delegatedAgentId": "<string>",
"guardrails": "<unknown>",
"guardrailState": "<unknown>",
"args": "<unknown>",
"startedAt": 123,
"completedAt": 123,
"error": "<string>",
"totalTokens": 123,
"totalCost": 123,
"parentRunId": "<string>",
"parentStepId": "<string>",
"outputs": "<unknown>",
"steps": [
{
"stepId": "<string>",
"status": "<string>",
"agent": "<string>",
"kind": "procedure",
"startedAt": 123,
"completedAt": 123,
"model": "<string>",
"totalTokens": 123,
"cost": 123,
"hold": {
"state": "waiting",
"heldAt": 123,
"resolvedAt": 123,
"approvalId": "<string>",
"handoff": {
"kind": "console",
"decidedBy": "person",
"item": "<string>",
"path": "<string>",
"url": "<string>"
}
}
}
],
"humanSteps": [
{
"nodeRunId": "<string>",
"stepId": "<string>",
"status": "waiting",
"attempt": 123,
"requestedAt": 123,
"escalatedAt": 123,
"completedAt": 123,
"handoff": {
"kind": "console",
"decidedBy": "person",
"item": "<string>",
"path": "<string>",
"url": "<string>"
}
}
],
"humanStepsPartial": true,
"handlingSummary": {
"disposition": "normal",
"expectedExceptionNodeIds": [
"<string>"
],
"handledFailureNodeIds": [
"<string>"
],
"unresolvedFailureNodeIds": [
"<string>"
]
},
"executionOutcome": {
"schemaVersion": 1,
"classifierRevision": 1,
"source": "native",
"attempt": 123,
"workflowInstanceId": "<string>",
"statusAtCapture": "completed",
"coverage": "complete",
"reasonCodes": [
"not_recorded"
],
"selectedPaths": [
{
"nodeId": "<string>",
"nodeName": "<string>",
"labels": [
"<string>"
]
}
],
"omittedPathCount": 1,
"capturedAt": 123,
"summary": {
"disposition": "normal",
"expectedExceptionNodeIds": [
"<string>"
],
"handledFailureNodeIds": [
"<string>"
],
"unresolvedFailureNodeIds": [
"<string>"
]
},
"graphDigest": "<string>"
},
"executionOutcomeReadReason": "not_recorded"
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "bad_request",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "forbidden",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "resource_missing",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.
v2 compatibility notes
Visibility
You read a run when your role grants holdruns:read at the run’s home (its own org unit, else its workflow’s owning org unit) and at every company it carries. Any other run, and a run with neither home, answers 404 exactly like a missing one.
Outputs
outputs is null until the run is completed. Then it is the run’s declared workflow outputs. A file-typed output is a file id: list the run’s files with listArtifacts and fetch bytes with GET /api/v2/files/content under files:read. The completedBy, completedVia and response keys a terminal human step records are removed, so a person’s identity, channel and free-text answer are never readable under runs:read.
Holds and human steps
Each step carrieshold: its governance hold’s state, heldAt, resolvedAt and opaque approvalId, with a person handoff while it is waiting. humanSteps lists each human step’s status, attempt and timestamps, oldest first, with a handoff while it is waiting or escalated. Give handoff.url (or handoff.path) to an eligible person, who decides in the Forge Console or with their own Personal key through completeHumanTask; a platform key or an External App cannot decide it. At most the newest 100 human steps are returned; humanStepsPartial: true says older ones were omitted.Authorizations
BearerAuthPlatformApiKeyPersonalKey
⌘I
Get run detail (with steps, human-step status and outputs)
curl --request GET \
--url https://api.forge.gloo.com/api/v3/runs/{runId} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.forge.gloo.com/api/v3/runs/{runId}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.forge.gloo.com/api/v3/runs/{runId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.forge.gloo.com/api/v3/runs/{runId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.forge.gloo.com/api/v3/runs/{runId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.forge.gloo.com/api/v3/runs/{runId}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.forge.gloo.com/api/v3/runs/{runId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": {
"id": "<string>",
"runType": "<string>",
"status": "<string>",
"interfaceId": "<string>",
"workflowId": "<string>",
"workflowVersion": 123,
"goal": "<string>",
"delegatedAgentId": "<string>",
"guardrails": "<unknown>",
"guardrailState": "<unknown>",
"args": "<unknown>",
"startedAt": 123,
"completedAt": 123,
"error": "<string>",
"totalTokens": 123,
"totalCost": 123,
"parentRunId": "<string>",
"parentStepId": "<string>",
"outputs": "<unknown>",
"steps": [
{
"stepId": "<string>",
"status": "<string>",
"agent": "<string>",
"kind": "procedure",
"startedAt": 123,
"completedAt": 123,
"model": "<string>",
"totalTokens": 123,
"cost": 123,
"hold": {
"state": "waiting",
"heldAt": 123,
"resolvedAt": 123,
"approvalId": "<string>",
"handoff": {
"kind": "console",
"decidedBy": "person",
"item": "<string>",
"path": "<string>",
"url": "<string>"
}
}
}
],
"humanSteps": [
{
"nodeRunId": "<string>",
"stepId": "<string>",
"status": "waiting",
"attempt": 123,
"requestedAt": 123,
"escalatedAt": 123,
"completedAt": 123,
"handoff": {
"kind": "console",
"decidedBy": "person",
"item": "<string>",
"path": "<string>",
"url": "<string>"
}
}
],
"humanStepsPartial": true,
"handlingSummary": {
"disposition": "normal",
"expectedExceptionNodeIds": [
"<string>"
],
"handledFailureNodeIds": [
"<string>"
],
"unresolvedFailureNodeIds": [
"<string>"
]
},
"executionOutcome": {
"schemaVersion": 1,
"classifierRevision": 1,
"source": "native",
"attempt": 123,
"workflowInstanceId": "<string>",
"statusAtCapture": "completed",
"coverage": "complete",
"reasonCodes": [
"not_recorded"
],
"selectedPaths": [
{
"nodeId": "<string>",
"nodeName": "<string>",
"labels": [
"<string>"
]
}
],
"omittedPathCount": 1,
"capturedAt": 123,
"summary": {
"disposition": "normal",
"expectedExceptionNodeIds": [
"<string>"
],
"handledFailureNodeIds": [
"<string>"
],
"unresolvedFailureNodeIds": [
"<string>"
]
},
"graphDigest": "<string>"
},
"executionOutcomeReadReason": "not_recorded"
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "bad_request",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "forbidden",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "resource_missing",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}
