cURL

curl --request GET \
  --url https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights \
  --header 'X-Session-Token: <api-key>'

import requests

url = "https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights"

headers = {"X-Session-Token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Session-Token': '<api-key>'}};

fetch('https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights', 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.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Session-Token: <api-key>"
  ],
]);

$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.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Session-Token", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights")

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

request = Net::HTTP::Get.new(url)
request["X-Session-Token"] = '<api-key>'

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

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "<string>",
    "attributes": {
      "totals": {
        "submissions": 123,
        "completed": 123,
        "rejected": 123,
        "cancelled": 123,
        "in_progress": 123
      },
      "return_rate": 123,
      "avg_end_to_end_minutes": 123,
      "active_submitters": 123,
      "steps": [
        {
          "id": "<string>",
          "name": "<string>",
          "avg_minutes": 123,
          "transitions": 123,
          "contributors": 123,
          "box": {
            "min": 123,
            "q1": 123,
            "median": 123,
            "q3": 123,
            "max": 123
          }
        }
      ],
      "truncated": true,
      "activity": {
        "bucket": "<string>",
        "series": [
          {
            "at": "2023-11-07T05:31:56Z",
            "transitions": 123,
            "steps": {}
          }
        ]
      },
      "baseline": {
        "totals": {
          "submissions": 123,
          "completed": 123,
          "rejected": 123,
          "cancelled": 123,
          "in_progress": 123
        },
        "return_rate": 123,
        "avg_end_to_end_minutes": 123,
        "active_submitters": 123,
        "steps": [
          {
            "id": "<string>",
            "name": "<string>",
            "avg_minutes": 123,
            "transitions": 123,
            "contributors": 123,
            "box": {
              "min": 123,
              "q1": 123,
              "median": 123,
              "q3": 123,
              "max": 123
            }
          }
        ],
        "truncated": true
      }
    },
    "meta": {
      "window": {
        "from": "2023-11-07T05:31:56Z",
        "to": "2023-11-07T05:31:56Z"
      },
      "cohort": {
        "scheme": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "contract": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    },
    "relationships": {
      "organisation": {
        "data": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "type": "<string>"
        }
      },
      "definition": {
        "data": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "type": "<string>"
        }
      }
    }
  },
  "jsonapi": {
    "version": "<string>"
  }
}

{
  "id": "98ca4a78-b66f-4234-9719-aaf832ee6669",
  "status": "400",
  "title": "A validation error was encountered",
  "source": {
    "parameter": "include"
  },
  "meta": {
    "resource": "wrong_value"
  }
}

{
  "id": "05fc9c8d-73b9-4697-9337-57f7a567a48f",
  "status": "401",
  "title": "You are not authorised to access this resource",
  "detail": "In order to access this resource, you need the 'admin' role.",
  "code": "AUTH.001"
}

{
  "id": "7b4c8f12-3e9a-4d5b-8c6f-1a2b3c4d5e6f",
  "status": "404",
  "title": "Resource not found",
  "detail": "The requested resource could not be found or does not exist.",
  "code": "NOT_FOUND.001"
}

{
  "id": "fe9d9a69-f0a7-4fdc-bb2c-176027f316c5",
  "status": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server."
}

Workflows

Get workflow insights

The aggregate figures for a workflow over a reporting window: volumes by outcome, return rate, average end-to-end time, active submitters and per-step timings with box-plot quartiles.

Everything is derived from the workflow’s transition records, under the caller’s own access — a principal whose grants reach only part of the workflow’s activity sees figures for that part. A submission that has never transitioned does not appear, and a submission whose earlier transitions predate the window is counted from its first transition inside it.

It also carries the transition volume over time, bucketed at the width asked for, so an activity chart does not need the records themselves.

The window is required. Optionally narrow the figures to a scheme’s or a contract’s submissions, and ask for include_baseline=true to get the unscoped figures alongside them for comparison.

Served by a hand-written handler rather than a generated one, because the resource is computed rather than stored.

GET

workflow-definitions

{workflow_definition_id}

insights

cURL

curl --request GET \
  --url https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights \
  --header 'X-Session-Token: <api-key>'

import requests

url = "https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights"

headers = {"X-Session-Token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Session-Token': '<api-key>'}};

fetch('https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights', 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.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Session-Token: <api-key>"
  ],
]);

$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.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Session-Token", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights")

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

request = Net::HTTP::Get.new(url)
request["X-Session-Token"] = '<api-key>'

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

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "<string>",
    "attributes": {
      "totals": {
        "submissions": 123,
        "completed": 123,
        "rejected": 123,
        "cancelled": 123,
        "in_progress": 123
      },
      "return_rate": 123,
      "avg_end_to_end_minutes": 123,
      "active_submitters": 123,
      "steps": [
        {
          "id": "<string>",
          "name": "<string>",
          "avg_minutes": 123,
          "transitions": 123,
          "contributors": 123,
          "box": {
            "min": 123,
            "q1": 123,
            "median": 123,
            "q3": 123,
            "max": 123
          }
        }
      ],
      "truncated": true,
      "activity": {
        "bucket": "<string>",
        "series": [
          {
            "at": "2023-11-07T05:31:56Z",
            "transitions": 123,
            "steps": {}
          }
        ]
      },
      "baseline": {
        "totals": {
          "submissions": 123,
          "completed": 123,
          "rejected": 123,
          "cancelled": 123,
          "in_progress": 123
        },
        "return_rate": 123,
        "avg_end_to_end_minutes": 123,
        "active_submitters": 123,
        "steps": [
          {
            "id": "<string>",
            "name": "<string>",
            "avg_minutes": 123,
            "transitions": 123,
            "contributors": 123,
            "box": {
              "min": 123,
              "q1": 123,
              "median": 123,
              "q3": 123,
              "max": 123
            }
          }
        ],
        "truncated": true
      }
    },
    "meta": {
      "window": {
        "from": "2023-11-07T05:31:56Z",
        "to": "2023-11-07T05:31:56Z"
      },
      "cohort": {
        "scheme": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "contract": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    },
    "relationships": {
      "organisation": {
        "data": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "type": "<string>"
        }
      },
      "definition": {
        "data": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "type": "<string>"
        }
      }
    }
  },
  "jsonapi": {
    "version": "<string>"
  }
}

{
  "id": "98ca4a78-b66f-4234-9719-aaf832ee6669",
  "status": "400",
  "title": "A validation error was encountered",
  "source": {
    "parameter": "include"
  },
  "meta": {
    "resource": "wrong_value"
  }
}

{
  "id": "05fc9c8d-73b9-4697-9337-57f7a567a48f",
  "status": "401",
  "title": "You are not authorised to access this resource",
  "detail": "In order to access this resource, you need the 'admin' role.",
  "code": "AUTH.001"
}

{
  "id": "7b4c8f12-3e9a-4d5b-8c6f-1a2b3c4d5e6f",
  "status": "404",
  "title": "Resource not found",
  "detail": "The requested resource could not be found or does not exist.",
  "code": "NOT_FOUND.001"
}

{
  "id": "fe9d9a69-f0a7-4fdc-bb2c-176027f316c5",
  "status": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server."
}

Authorizations

X-Session-Token

string

header

required

Session token for authentication.

Path Parameters

workflow_definition_id

string<uuid>

required

The unique identifier for the workflow.

Query Parameters

filter

string

required

Narrows the transition records the figures are computed from.

The reporting window is required — an unbounded window would mean aggregating the whole collection, so it is rejected rather than served:

ge(created_at,xxx): the start of the window. Required.
le(created_at,xxx): the end of the window. Required.

The cohort filters are optional and mutually exclusive. Both resolve to a set of submissions server-side, through the operation a submission captured:

eq(scheme,xxx): only submissions whose payload operation belongs to the scheme.
eq(contract,xxx): as scheme, expanded across every scheme in the contract.

A submission that captured no operation cannot join a scheme or a contract, so it is invisible to both cohorts. Unscoped figures include it.

The organisation is not a filter — it is the organisation that owns the workflow definition in the path.

For more information on using named filters, see the docs

Minimum string length: 1

bucket

enum<string>

default:1d

The bucket width for the activity series. The five widths are the ones an activity chart picks between as the reporting window widens, from five minutes over a few hours to a week over a year.

Available options:

5m,

1h,

6h,

1d,

1w

include_baseline

boolean

default:false

Adds a baseline block to the attributes: the same figures over the same window with the cohort filter dropped, so a cohort can be read against the whole network. Costs one extra aggregation, not an extra round trip.

Response

The aggregate figures for the workflow definition over the requested window

JSON API response object

data

object

required

The aggregate view of one workflow definition's activity over a reporting window. A synthetic, read-only resource: it is computed from the workflow transition records the caller can see, never stored, and its identifier is the workflow definition it was computed for.

Show child attributes

jsonapi

object

required

Show child attributes