Workflow Run API

Count Workflow Runs

Count workflow runs matching the same filters as Search Workflow Runs (workflow ID, status, user IDs, time range, linked ticket, parent run, include_child_runs, include_runs_with_linked_ticket). Use this instead of paging the full result set when only the total is needed — e.g. dashboard tiles or sizing a backfill before running it. The count walks the full filtered set, so latency scales with how many rows match; on teams with millions of runs, narrow the count with created_after/created_before (very broad counts may hit the server’s query timeout).

POST

workflow-runs

count

Count Workflow Runs

curl --request POST \
  --url https://public.api.serval.com/v2/workflow-runs/count \
  --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>",
  "parentWorkflowRunId": "<string>",
  "includeChildRuns": true,
  "includeRunsWithLinkedTicket": true
}
'

import requests

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

payload = {
    "teamId": "<string>",
    "workflowId": "<string>",
    "statuses": [],
    "targetUserId": "<string>",
    "initiatedByUserId": "<string>",
    "createdAfter": "<string>",
    "createdBefore": "<string>",
    "linkedTicketId": "<string>",
    "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>',
    parentWorkflowRunId: '<string>',
    includeChildRuns: true,
    includeRunsWithLinkedTicket: true
  })
};

fetch('https://public.api.serval.com/v2/workflow-runs/count', 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/count",
  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>',
    '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/count"

	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  \"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/count")
  .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  \"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/count")

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  \"parentWorkflowRunId\": \"<string>\",\n  \"includeChildRuns\": true,\n  \"includeRunsWithLinkedTicket\": true\n}"

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

{
  "count": 123
}

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

Same filter set as SearchWorkflowRunsRequest, minus pagination and include_output — the two requests must stay filter-compatible so a caller can count a result set and then page exactly that set.

teamId

string

The ID of the team. Required.

workflowId

string | null

The workflow UUID. Not a wf_ scoped 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.

parentWorkflowRunId

string | null

Count only the direct child runs (sub-workflows) of this parent run.

includeChildRuns

boolean | null

Whether to include child runs (sub-workflows) in the count. Unset means true (matches include_output's unset-means-true convention). Set explicitly to false to count only top-level runs. include_child_runs=false is mutually exclusive with parent_workflow_run_id; combining them is a 400.

includeRunsWithLinkedTicket

boolean | null

When true, count only runs that are linked to a ticket (linked_ticket_id set). Unset and explicit false are equivalent — no filter is applied.

Response

200 - application/json

Success

count

The number of workflow runs matching the filters.

Count Workflow Runs

curl --request POST \
  --url https://public.api.serval.com/v2/workflow-runs/count \
  --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>",
  "parentWorkflowRunId": "<string>",
  "includeChildRuns": true,
  "includeRunsWithLinkedTicket": true
}
'

import requests

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

payload = {
    "teamId": "<string>",
    "workflowId": "<string>",
    "statuses": [],
    "targetUserId": "<string>",
    "initiatedByUserId": "<string>",
    "createdAfter": "<string>",
    "createdBefore": "<string>",
    "linkedTicketId": "<string>",
    "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>',
    parentWorkflowRunId: '<string>',
    includeChildRuns: true,
    includeRunsWithLinkedTicket: true
  })
};

fetch('https://public.api.serval.com/v2/workflow-runs/count', 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/count",
  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>',
    '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/count"

	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  \"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/count")
  .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  \"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/count")

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  \"parentWorkflowRunId\": \"<string>\",\n  \"includeChildRuns\": true,\n  \"includeRunsWithLinkedTicket\": true\n}"

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

{
  "count": 123
}

Get started

Authentication

Endpoints

Development

Count Workflow Runs

Authentication and permissions

Authorizations

Body

Response

​Authentication and permissions

Authorizations

Body

Response

Authentication and permissions