Workflow Run API

Search Workflow Runs

Search workflow runs with filters. Supports filtering by workflow ID, status, user IDs, time range, linked ticket, and parent_workflow_run_id. Set include_child_runs=false to exclude child runs (runs spawned by another run), or include_runs_with_linked_ticket=true to return only ticket-linked runs — both avoid paging rows a caller would otherwise discard client-side. To investigate a run’s sub-workflows, search with parent_workflow_run_id set to that run’s id (combine with statuses=[FAILED] to find failing children), then recurse into each child run.

POST

workflow-runs

curl --request POST \
  --url https://public.api.serval.com/v2/workflow-runs/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "teamId": "<string>",
  "workflowId": "<string>",
  "statuses": [],
  "targetUserId": "<string>",
  "initiatedByUserId": "<string>",
  "createdAfter": "<string>",
  "createdBefore": "<string>",
  "linkedTicketId": "<string>",
  "pageSize": 123,
  "pageToken": "<string>",
  "includeOutput": true,
  "parentWorkflowRunId": "<string>",
  "includeChildRuns": true,
  "includeRunsWithLinkedTicket": true
}
'

import requests

url = "https://public.api.serval.com/v2/workflow-runs/search"

payload = {
    "teamId": "<string>",
    "workflowId": "<string>",
    "statuses": [],
    "targetUserId": "<string>",
    "initiatedByUserId": "<string>",
    "createdAfter": "<string>",
    "createdBefore": "<string>",
    "linkedTicketId": "<string>",
    "pageSize": 123,
    "pageToken": "<string>",
    "includeOutput": True,
    "parentWorkflowRunId": "<string>",
    "includeChildRuns": True,
    "includeRunsWithLinkedTicket": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    teamId: '<string>',
    workflowId: '<string>',
    statuses: [],
    targetUserId: '<string>',
    initiatedByUserId: '<string>',
    createdAfter: '<string>',
    createdBefore: '<string>',
    linkedTicketId: '<string>',
    pageSize: 123,
    pageToken: '<string>',
    includeOutput: true,
    parentWorkflowRunId: '<string>',
    includeChildRuns: true,
    includeRunsWithLinkedTicket: true
  })
};

fetch('https://public.api.serval.com/v2/workflow-runs/search', 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://public.api.serval.com/v2/workflow-runs/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'teamId' => '<string>',
    'workflowId' => '<string>',
    'statuses' => [
        
    ],
    'targetUserId' => '<string>',
    'initiatedByUserId' => '<string>',
    'createdAfter' => '<string>',
    'createdBefore' => '<string>',
    'linkedTicketId' => '<string>',
    'pageSize' => 123,
    'pageToken' => '<string>',
    'includeOutput' => true,
    'parentWorkflowRunId' => '<string>',
    'includeChildRuns' => true,
    'includeRunsWithLinkedTicket' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://public.api.serval.com/v2/workflow-runs/search"

	payload := strings.NewReader("{\n  \"teamId\": \"<string>\",\n  \"workflowId\": \"<string>\",\n  \"statuses\": [],\n  \"targetUserId\": \"<string>\",\n  \"initiatedByUserId\": \"<string>\",\n  \"createdAfter\": \"<string>\",\n  \"createdBefore\": \"<string>\",\n  \"linkedTicketId\": \"<string>\",\n  \"pageSize\": 123,\n  \"pageToken\": \"<string>\",\n  \"includeOutput\": true,\n  \"parentWorkflowRunId\": \"<string>\",\n  \"includeChildRuns\": true,\n  \"includeRunsWithLinkedTicket\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://public.api.serval.com/v2/workflow-runs/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"teamId\": \"<string>\",\n  \"workflowId\": \"<string>\",\n  \"statuses\": [],\n  \"targetUserId\": \"<string>\",\n  \"initiatedByUserId\": \"<string>\",\n  \"createdAfter\": \"<string>\",\n  \"createdBefore\": \"<string>\",\n  \"linkedTicketId\": \"<string>\",\n  \"pageSize\": 123,\n  \"pageToken\": \"<string>\",\n  \"includeOutput\": true,\n  \"parentWorkflowRunId\": \"<string>\",\n  \"includeChildRuns\": true,\n  \"includeRunsWithLinkedTicket\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/workflow-runs/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"teamId\": \"<string>\",\n  \"workflowId\": \"<string>\",\n  \"statuses\": [],\n  \"targetUserId\": \"<string>\",\n  \"initiatedByUserId\": \"<string>\",\n  \"createdAfter\": \"<string>\",\n  \"createdBefore\": \"<string>\",\n  \"linkedTicketId\": \"<string>\",\n  \"pageSize\": 123,\n  \"pageToken\": \"<string>\",\n  \"includeOutput\": true,\n  \"parentWorkflowRunId\": \"<string>\",\n  \"includeChildRuns\": true,\n  \"includeRunsWithLinkedTicket\": true\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "<string>",
      "workflowId": "<string>",
      "teamId": "<string>",
      "status": "WORKFLOW_RUN_STATUS_UNSPECIFIED",
      "createdAt": "<string>",
      "completedAt": "<string>",
      "initiatedByUserId": "<string>",
      "targetUserId": "<string>",
      "inputs": "<string>",
      "output": "<string>",
      "linkedTicketId": "<string>",
      "approvalRequestId": "<string>",
      "statusUpdatedAt": "<string>",
      "parentWorkflowRunId": "<string>",
      "parentWorkflowRunStepNumber": 123
    }
  ],
  "nextPageToken": "<string>"
}

Authentication and permissions

Token requirements: User-based token (OAuth) or Organization-scoped API key or Team-scoped API key. Send a bearer access token for one of these identities. The permissions and resource restrictions below also apply.

Credential	Access requirements
Organization-scoped API key	`workflows:read`
Team-scoped API key	`workflows:read`
User-based token (OAuth)	Supported, subject to permissions

Permissions joined by + are all required; or separates alternatives. Full-access keys still cannot call endpoints marked unsupported. Team keys must allow every team checked by the request. OAuth access depends on the user’s roles and resource access.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

teamId

string

The ID of the team. Required.

workflowId

string | null

Filter by workflow ID.

statuses

enum<string>[]

Filter by statuses (multiple allowed).

Available options:

WORKFLOW_RUN_STATUS_UNSPECIFIED,

WORKFLOW_RUN_STATUS_PENDING,

WORKFLOW_RUN_STATUS_RUNNING,

WORKFLOW_RUN_STATUS_COMPLETED,

WORKFLOW_RUN_STATUS_FAILED,

WORKFLOW_RUN_STATUS_DENIED,

WORKFLOW_RUN_STATUS_CANCELED

targetUserId

string | null

Filter by the target user for the workflow run.

initiatedByUserId

string | null

Filter by the user who initiated the workflow run.

createdAfter

string | null

Filter by runs created after this timestamp (RFC3339 format).

createdBefore

string | null

Filter by runs created before this timestamp (RFC3339 format).

linkedTicketId

string | null

Filter by linked ticket ID.

pageSize

integer<int32> | null

Maximum number of results to return. Default is 50, maximum is 200. Larger values are silently coerced server-side; the actual value used is returned in the X-Served-Page-Size response header.

pageToken

string | null

Token for pagination. Leave empty for the first request.

includeOutput

boolean | null

When true (default), each returned run includes its output field (the full workflow result). For multi-row search responses this can be megabytes per row — set to false if you only need run metadata; you can then fetch full output per-run via GetWorkflowRun. Strongly recommended false for any caller that does not need output.

parentWorkflowRunId

string | null

Filter to the direct child runs (sub-workflows) of this parent run. Pass a run ID here to list the runs it spawned one level deep; combine with statuses (e.g. FAILED) to find the failing children.

includeChildRuns

boolean | null

Whether to include child runs (sub-workflows) in the results. Unset means true (all runs are returned — matches include_output's unset-means-true convention). Set explicitly to false to return only top-level runs; on journey-heavy teams child runs can be >90% of total rows, so this avoids paging them just to discard them client-side. include_child_runs=false is mutually exclusive with parent_workflow_run_id (a run cannot both have a given parent and no parent); combining them is a 400.

includeRunsWithLinkedTicket

boolean | null

When true, return only runs that are linked to a ticket (linked_ticket_id set). Unset and explicit false are equivalent — no filter is applied. Useful for building per-ticket run indexes without fetching unlinked runs.

Response

200 - application/json

Success

data

WorkflowRun · object[]

The list of workflow runs.

Show child attributes

nextPageToken

string | null

Token for retrieving the next page of results. Empty if no more results.

Search Workflow Runs

curl --request POST \
  --url https://public.api.serval.com/v2/workflow-runs/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "teamId": "<string>",
  "workflowId": "<string>",
  "statuses": [],
  "targetUserId": "<string>",
  "initiatedByUserId": "<string>",
  "createdAfter": "<string>",
  "createdBefore": "<string>",
  "linkedTicketId": "<string>",
  "pageSize": 123,
  "pageToken": "<string>",
  "includeOutput": true,
  "parentWorkflowRunId": "<string>",
  "includeChildRuns": true,
  "includeRunsWithLinkedTicket": true
}
'

import requests

url = "https://public.api.serval.com/v2/workflow-runs/search"

payload = {
    "teamId": "<string>",
    "workflowId": "<string>",
    "statuses": [],
    "targetUserId": "<string>",
    "initiatedByUserId": "<string>",
    "createdAfter": "<string>",
    "createdBefore": "<string>",
    "linkedTicketId": "<string>",
    "pageSize": 123,
    "pageToken": "<string>",
    "includeOutput": True,
    "parentWorkflowRunId": "<string>",
    "includeChildRuns": True,
    "includeRunsWithLinkedTicket": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    teamId: '<string>',
    workflowId: '<string>',
    statuses: [],
    targetUserId: '<string>',
    initiatedByUserId: '<string>',
    createdAfter: '<string>',
    createdBefore: '<string>',
    linkedTicketId: '<string>',
    pageSize: 123,
    pageToken: '<string>',
    includeOutput: true,
    parentWorkflowRunId: '<string>',
    includeChildRuns: true,
    includeRunsWithLinkedTicket: true
  })
};

fetch('https://public.api.serval.com/v2/workflow-runs/search', 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://public.api.serval.com/v2/workflow-runs/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'teamId' => '<string>',
    'workflowId' => '<string>',
    'statuses' => [
        
    ],
    'targetUserId' => '<string>',
    'initiatedByUserId' => '<string>',
    'createdAfter' => '<string>',
    'createdBefore' => '<string>',
    'linkedTicketId' => '<string>',
    'pageSize' => 123,
    'pageToken' => '<string>',
    'includeOutput' => true,
    'parentWorkflowRunId' => '<string>',
    'includeChildRuns' => true,
    'includeRunsWithLinkedTicket' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://public.api.serval.com/v2/workflow-runs/search"

	payload := strings.NewReader("{\n  \"teamId\": \"<string>\",\n  \"workflowId\": \"<string>\",\n  \"statuses\": [],\n  \"targetUserId\": \"<string>\",\n  \"initiatedByUserId\": \"<string>\",\n  \"createdAfter\": \"<string>\",\n  \"createdBefore\": \"<string>\",\n  \"linkedTicketId\": \"<string>\",\n  \"pageSize\": 123,\n  \"pageToken\": \"<string>\",\n  \"includeOutput\": true,\n  \"parentWorkflowRunId\": \"<string>\",\n  \"includeChildRuns\": true,\n  \"includeRunsWithLinkedTicket\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://public.api.serval.com/v2/workflow-runs/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"teamId\": \"<string>\",\n  \"workflowId\": \"<string>\",\n  \"statuses\": [],\n  \"targetUserId\": \"<string>\",\n  \"initiatedByUserId\": \"<string>\",\n  \"createdAfter\": \"<string>\",\n  \"createdBefore\": \"<string>\",\n  \"linkedTicketId\": \"<string>\",\n  \"pageSize\": 123,\n  \"pageToken\": \"<string>\",\n  \"includeOutput\": true,\n  \"parentWorkflowRunId\": \"<string>\",\n  \"includeChildRuns\": true,\n  \"includeRunsWithLinkedTicket\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/workflow-runs/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"teamId\": \"<string>\",\n  \"workflowId\": \"<string>\",\n  \"statuses\": [],\n  \"targetUserId\": \"<string>\",\n  \"initiatedByUserId\": \"<string>\",\n  \"createdAfter\": \"<string>\",\n  \"createdBefore\": \"<string>\",\n  \"linkedTicketId\": \"<string>\",\n  \"pageSize\": 123,\n  \"pageToken\": \"<string>\",\n  \"includeOutput\": true,\n  \"parentWorkflowRunId\": \"<string>\",\n  \"includeChildRuns\": true,\n  \"includeRunsWithLinkedTicket\": true\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "<string>",
      "workflowId": "<string>",
      "teamId": "<string>",
      "status": "WORKFLOW_RUN_STATUS_UNSPECIFIED",
      "createdAt": "<string>",
      "completedAt": "<string>",
      "initiatedByUserId": "<string>",
      "targetUserId": "<string>",
      "inputs": "<string>",
      "output": "<string>",
      "linkedTicketId": "<string>",
      "approvalRequestId": "<string>",
      "statusUpdatedAt": "<string>",
      "parentWorkflowRunId": "<string>",
      "parentWorkflowRunStepNumber": 123
    }
  ],
  "nextPageToken": "<string>"
}

Get started

Authentication

Endpoints

Development

Search Workflow Runs

Authentication and permissions

Authorizations

Body

Response

​Authentication and permissions

Authorizations

Body

Response

Authentication and permissions