> ## Documentation Index > Fetch the complete documentation index at: https://docs.ctrl-hub.com/llms.txt > Use this file to discover all available pages before exploring further. # List workflow submission journeys > The per-submission journeys behind the aggregate figures: for each submission that transitioned inside the window, its status, current step, start and finish, elapsed time, step count, whether it was sent back, and every stage it passed through. The operators are side-loaded, so their names are available without a second read. Takes the same required window and the same optional cohort filters as the aggregate, so a page of journeys always reconciles with the figures above it. Send `Accept: text/csv` (or `format=csv`) for the export instead of a page: `shape=transitions` for one row per transition, `shape=summary` for one row per submission. The export ignores pagination and covers the whole window. A window the server had to bound is reported as `meta.stats.truncated` on the JSON response, and as an `X-Insights-Truncated` header on the export, where a spreadsheet cannot carry the caveat itself. Served by a hand-written handler rather than a generated one, because the resource is computed rather than stored. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v3/workflow-definitions/{workflow_definition_id}/insights/submissions openapi: 3.1.0 info: contact: email: support@ctrl-hub.com name: Ctrl Hub url: https://www.ctrl-hub.com description: > Ctrl Hub is the all-in-one platform for high-risk industries like utilities, construction, infrastructure, and renewables. We help teams manage everything from risk assessments and HAVS exposure to vehicle and equipment checks, with a guaranteed minimum of 200% ROI. license: name: MIT License url: https://opensource.org/licenses/MIT summary: An API for managing your compliance and risk posture termsOfService: https://www.ctrl-hub.com/terms-conditions title: Ctrl Hub version: 1.0.0 servers: - description: Production url: https://api.ctrl-hub.com - description: Staging url: https://api.ctrl-hub.dev - description: Development url: https://api.ctrl-hub.run security: [] tags: - description: | Actions are follow-ups assigned to users and teams, produced manually or by domain producers such as the data-capture workflow runner. name: Actions - description: | Audit events are the events that are logged by the system. name: Audit Events - description: | View the platform's health and availability. name: Status - description: > User-owned dashboards composed of cards on a fixed-slot bento layout. Cards come from a per-domain registry; the API stores their config as opaque JSON. name: Dashboards - description: > A record of documents the platform generated and handed over, retained as evidence of what was issued. `subject_type` says what kind of records an export covers, and it is what decides how the request is authorised: there is no export permission of its own, so if you can see the records you can export them. name: Exports - description: > Scheduled delivery of a saved query's results, as a CSV attachment or a summary email. Every run is retained with the file it sent, so what a recipient received stays retrievable. A report runs as the person who created it, under their own access. name: Reports - description: | Manage appointments for work to be carried out with your customers name: Customer Appointments - description: | Manage interactions you have with your customers name: Customer Interactions - description: | Manage accounts for your customers name: Customer Accounts and Contacts - description: | Qualifications are the skills and knowledge that an organisation requires. name: Qualifications - description: | Workflows allow you to automate your processes. name: Workflows - description: | Manage documents name: Documents - description: | Manage documents name: Folders - description: | Manage documents name: Document Reviews - description: | Manage feature configurations for an organisation. name: Feature Configurations - description: | Equipment are the physical assets that an organisation manages. name: Equipment - description: | The central cost register: time-versioned rate codes for material, labour, contractor and miscellaneous spend, used to cost work against the job hierarchy. name: Costs - description: > Locations are places an organisation manages, optionally classified by a location type. name: Locations - description: | Manage your forms and their schemas name: Forms, Schemas and Categories - description: | Create and view form submissions name: Submissions - description: | View the roles available in the system. name: IAM Roles - description: > IAM role groups can be assigned to principals to manage authorisation centrally. name: IAM Role Groups - description: | Manage service accounts which can access the API programmatically. name: Service Accounts - description: | Manage bridges between organisations. name: Bridges - description: | Manage settings for an organisation. name: Settings - description: | Manage teams within an organisation. name: Teams - description: | Manage job roles within an organisation. name: Job Roles - description: | Manage users and accounts. name: Users - description: | Invite and manage invitations to organisations. name: Invitations - description: > IAM grants are the asignment of roles or permissions to principals to manage resource access. name: IAM Grants - description: | View the permissions available in the system. name: IAM Permissions - description: | SSO providers are the identity providers for an organisation. name: SSO Providers - description: | Whoami returns information about the currently authenticated principal. name: Whoami - description: | Manage your images name: Images - description: > AI agent personas that synthesise data into role-specific intelligent briefings. name: Agents - description: | Briefings generated by AI agents, including reasoning traces. name: Briefings - description: > Organisations are the center point for most resources in the platform. Most other endpoints are subresources of an organisation. name: Organisations - description: | Permits managements, integrated with street manager. name: Permits - description: | Projects manage your work and governance. name: Projects - description: > Import templates allow users to save and reuse their CSV importer configuration as named templates. name: Import Templates - description: | Properties are the physical locations. name: Properties - description: | Search across schemes, work orders, and operations. name: Search - description: | Provides the API specification in JSON and YAML formats name: Specifications - description: | Streets are the physical roads. name: Streets - description: | Integration with street manager name: Street Manager - description: | Vehicles are the physical vehicles that an organisation manages. name: Vehicles - description: > Scheme contracts (also known as regions) group schemes allocated from the network to a contractor. name: Scheme Contracts - description: > Scheme shares allow you to share your schemes with other organisations across bridges. name: Scheme Shares - description: | Schemes are large programmes of work name: Schemes - description: | Work orders the component parts of a scheme. name: Work Orders - description: | Operations are the work to be carried out within work orders. name: Operations externalDocs: description: More documentation and resources url: https://docs.ctrl-hub.com paths: /v3/workflow-definitions/{workflow_definition_id}/insights/submissions: get: tags: - Workflows description: > The per-submission journeys behind the aggregate figures: for each submission that transitioned inside the window, its status, current step, start and finish, elapsed time, step count, whether it was sent back, and every stage it passed through. The operators are side-loaded, so their names are available without a second read. Takes the same required window and the same optional cohort filters as the aggregate, so a page of journeys always reconciles with the figures above it. Send `Accept: text/csv` (or `format=csv`) for the export instead of a page: `shape=transitions` for one row per transition, `shape=summary` for one row per submission. The export ignores pagination and covers the whole window. A window the server had to bound is reported as `meta.stats.truncated` on the JSON response, and as an `X-Insights-Truncated` header on the export, where a spreadsheet cannot carry the caveat itself. Served by a hand-written handler rather than a generated one, because the resource is computed rather than stored. operationId: ListWorkflowInsightSubmissions parameters: - $ref: '#/components/parameters/workflow_definition_id' - $ref: '#/components/parameters/workflow_insights_filter' - $ref: '#/components/parameters/workflow_insight_submissions_sort' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/insights_format' - $ref: '#/components/parameters/insights_shape' responses: '200': $ref: '#/components/responses/ListWorkflowInsightSubmissions' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorised' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' security: - Session: [] - OAuth2: [] - Cookie: [] components: parameters: workflow_definition_id: name: workflow_definition_id in: path required: true description: The unique identifier for the workflow. schema: type: string format: uuid example: 02a41ff2-1436-42df-b168-900153e2d993 workflow_insights_filter: name: filter in: query description: > 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](https://docs.ctrl-hub.com/api-reference/features#filtering) required: true schema: type: string minLength: 1 workflow_insight_submissions_sort: in: query name: sort description: > The field to order the journeys by. One field only, and the schema refuses a second: there is no secondary sort behind it, so a second value would have had no effect on the order it came back in. Defaults to `-started_at`, the most recently started first. Submissions still in progress have no elapsed time, so they sort last under both `elapsed_minutes` and `-elapsed_minutes`. required: false style: form explode: false schema: type: array maxItems: 1 items: type: string enum: - started_at - '-started_at' - elapsed_minutes - '-elapsed_minutes' limit: name: limit in: query description: Limit the number of resources returned by the API required: false schema: type: integer format: int64 minimum: 1 default: 100 offset: name: offset in: query description: Offset the resources returned by the API required: false schema: type: integer format: int64 minimum: 0 default: 0 insights_format: name: format in: query description: > Asks for the CSV export rather than a page of journeys. `format=csv` is equivalent to sending `Accept: text/csv`, and exists so the export is a plain URL — the form a browser download or a scheduled delivery can use without setting a header. required: false schema: type: string enum: - csv insights_shape: name: shape in: query description: > The shape of the CSV export. `transitions` writes one row per transition — the stage-by-stage trail behind each submission. `summary` writes one row per submission. Ignored unless CSV was asked for. required: false schema: type: string default: transitions enum: - transitions - summary responses: ListWorkflowInsightSubmissions: description: > A page of the workflow's submission journeys, or the whole set as CSV when `text/csv` was asked for. headers: X-Insights-Truncated: description: > Present and `true` when the server bounded the window before assembling the journeys, so the page, the total and the export all cover only part of it. schema: type: string Content-Type: $ref: '#/components/headers/content-type' Content-Length: $ref: '#/components/headers/content-length' X-Request-ID: $ref: '#/components/headers/x-request-id' content: application/vnd.api+json: schema: allOf: - type: object required: - data properties: data: title: A list of workflow submission journeys type: array items: $ref: '#/components/schemas/WorkflowInsightSubmission' included: $ref: '#/components/schemas/WorkflowInsightSubmissionIncludes' - $ref: '#/components/schemas/JSONAPI' - $ref: '#/components/schemas/DocumentMeta' - type: object properties: meta: type: object properties: stats: type: object required: - truncated properties: truncated: type: boolean description: > True when the server bounded the window before assembling the journeys, so the page and the total cover only part of it. The export reports the same thing as an `X-Insights-Truncated` header, since a spreadsheet cannot carry the caveat. text/csv: schema: type: string description: > The journeys as comma-separated values. `shape=transitions` (the default) writes one row per transition, `shape=summary` one row per submission. Pagination does not apply — the export covers the whole window, up to the server's aggregation bound. BadRequest: description: > There was an error with the request - this could be due to an invalid body, query parameters, or headers that were sent to the API. headers: Content-Type: $ref: '#/components/headers/content-type' Content-Length: $ref: '#/components/headers/content-length' X-Request-ID: $ref: '#/components/headers/x-request-id' content: application/vnd.api+json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' example: id: 98ca4a78-b66f-4234-9719-aaf832ee6669 status: '400' title: A validation error was encountered source: parameter: include meta: resource: wrong_value Unauthorised: description: Authentication failed headers: Content-Type: $ref: '#/components/headers/content-type' Content-Length: $ref: '#/components/headers/content-length' X-Request-ID: $ref: '#/components/headers/x-request-id' content: application/vnd.api+json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' example: 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 NotFound: description: The requested resource could not be found headers: Content-Type: $ref: '#/components/headers/content-type' Content-Length: $ref: '#/components/headers/content-length' X-Request-ID: $ref: '#/components/headers/x-request-id' content: application/vnd.api+json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' example: 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 InternalServerError: description: There was a problem handling the request on the server side headers: Content-Type: $ref: '#/components/headers/content-type' Content-Length: $ref: '#/components/headers/content-length' X-Request-ID: $ref: '#/components/headers/x-request-id' content: application/vnd.api+json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' example: id: fe9d9a69-f0a7-4fdc-bb2c-176027f316c5 status: '500' title: Internal Server Error detail: An unexpected error occurred on the server. headers: content-type: description: The content type of the response schema: type: string example: application/vnd.api+json content-length: description: The length of the response body in bytes schema: type: integer format: int32 example: 1234 x-request-id: description: >- An ID that can be provided when reporting bugs to help identify the issue schema: type: string example: 8470f56af4cf25e22be08e72c70dbbdc schemas: WorkflowInsightSubmission: type: object description: > One submission's passage through a workflow over a reporting window, assembled from its transition records. A synthetic, read-only resource: its identifier is the submission's. required: - id - type - attributes - relationships properties: id: type: string format: uuid description: The unique identifier of the form submission. type: type: string const: workflow-insight-submissions attributes: $ref: '#/components/schemas/WorkflowInsightSubmissionAttributes' relationships: $ref: '#/components/schemas/WorkflowInsightSubmissionRelationships' WorkflowInsightSubmissionIncludes: type: array description: > Resources side-loaded with a page of workflow journeys. The operators are always side-loaded, so a caller can render the names on a journey without a second read. items: discriminator: propertyName: type mapping: users: $ref: '#/components/schemas/User' oneOf: - $ref: '#/components/schemas/User' JSONAPI: type: object description: JSON API response object required: - jsonapi properties: jsonapi: type: object required: - version properties: version: type: string description: The version of the JSON API specification examples: - '1.0' DocumentMeta: type: object description: Document level meta about the resources on the server in list endpoints. required: - meta properties: meta: type: object required: - pagination properties: features: $ref: '#/components/schemas/Features' pagination: $ref: '#/components/schemas/Pagination' Error: type: object description: An error response properties: id: description: >- A unique identifier for this particular occurrence of the problem. If you encounter this, please provide us with the error ID and we can investigate it on our side. type: string format: uuid examples: - 05fc9c8d-73b9-4697-9337-57f7a567a48f status: description: >- The status code for the error. This might not match the HTTP status code if there are more that one errors to return with different status codes. type: string examples: - '401' - '500' title: description: A human readable title for the error. type: string examples: - You are not authorised to access this resource detail: description: >- Where there is more detail that we can provide outside of the title, we will provide it here. type: string examples: - In order to access this resource, you need the 'admin' role. code: description: >- A unique code for the error that may help us to diagnose the issue. Not all errors have codes, so this is usually empty. type: string examples: - AUTH.001 source: description: A JSON object containing additional information about the error. type: object properties: pointer: description: >- A JSON Pointer to the value in the request that caused the error. type: string examples: - /data/attributes/email parameter: description: >- A string indicating which query parameter in the request caused the error. type: string examples: - include required: - id - status - title WorkflowInsightSubmissionAttributes: type: object description: Attributes for one submission's workflow journey required: - status - current_step - started_at - finished_at - elapsed_minutes - step_count - returned - stages properties: status: type: string description: | The type of the step the submission last moved into, normally one of `initial`, `intermediate`, `completed`, `rejected` or `cancelled`. The last three are terminal. current_step: type: string description: The name of the step the submission last moved into. started_at: type: string format: date-time description: > When the submission's first transition **inside the window** was recorded. Not when the submission was created, and not when it entered the workflow, unless both fall inside the window. finished_at: type: - string - 'null' format: date-time description: >- When the terminal transition was recorded, or null while the submission is still in progress. elapsed_minutes: type: - integer - 'null' description: >- Whole minutes from `started_at` to `finished_at`, or null while the submission is still in progress. step_count: type: integer description: The number of transitions the submission made inside the window. returned: type: boolean description: >- True when the submission left the same step more than once, i.e. it was sent back. stages: type: array description: The submission's transitions inside the window, oldest first. items: type: object required: - from - to - at - operator - minutes_in_step - note properties: from: type: object description: The step the submission moved out of. required: - id - name properties: id: type: string description: >- The identifier of the step within the workflow definition version. name: type: string description: The name of the step. to: type: object description: The step the submission moved in to. required: - id - name - status properties: id: type: string description: >- The identifier of the step within the workflow definition version. name: type: string description: The name of the step. status: type: string description: >- The type of the step, one of `initial`, `intermediate`, `completed`, `rejected` or `cancelled`. at: type: string format: date-time description: When the transition was recorded. operator: type: - string - 'null' format: uuid description: > The user who recorded the transition, as an identifier resolvable against the side-loaded operators. Null where the transition carries no author, which is how a transition made by a job rather than a person reads. minutes_in_step: type: - integer - 'null' description: > Whole minutes spent in `from`, measured as the gap to the preceding transition. Null on the submission's first stage in the window, where the preceding transition falls outside it and the real figure is unknowable from the window alone. note: type: string description: >- The note recorded against the transition, empty where none was given. WorkflowInsightSubmissionRelationships: type: object description: Relationships for one submission's workflow journey required: - submission - operators - definition properties: submission: type: object required: - data properties: data: $ref: '#/components/schemas/FormSubmissionRelationship' operators: type: object description: >- The distinct users who recorded a transition on the submission, in the order they acted. required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' definition: type: object required: - data properties: data: $ref: '#/components/schemas/WorkflowDefinitionRelationship' User: type: object description: A user required: - id - type - attributes properties: id: type: string format: uuid description: The unique identifier of the user. examples: - 123e4567-e89b-12d3-a456-426614174000 type: type: string const: users attributes: $ref: '#/components/schemas/UserAttributes' meta: $ref: '#/components/schemas/UserMeta' relationships: $ref: '#/components/schemas/UserRelationships' Features: type: object description: Represents feature configurations of the API properties: include: type: object properties: options: type: array items: type: string examples: - related.resource Pagination: type: object description: Represents pagination details for API responses required: - counts - current_page - offsets - requested properties: counts: type: object required: - pages - resources properties: pages: type: integer examples: - 1 resources: type: integer examples: - 1 current_page: type: integer examples: - 1 offsets: type: object required: - next - previous properties: next: type: - integer - 'null' examples: - null previous: type: - integer - 'null' examples: - null requested: type: object required: - limit - offset properties: limit: type: integer examples: - 10 offset: type: integer examples: - 0 FormSubmissionRelationship: type: object description: Represents a relationship to a form submission required: - id - type properties: id: type: string format: uuid description: The unique identifier of the form submission type: type: string const: form-submissions UserRelationship: type: object description: Represents a relationship to a user required: - id - type properties: id: type: string format: uuid description: The unique identifier of the user type: type: string const: users WorkflowDefinitionRelationship: type: object description: Represents a relationship to a workflow definition required: - id - type properties: id: type: string format: uuid description: The unique identifier of the workflow definition type: type: string const: workflow-definitions UserAttributes: type: object description: Attributes for a user properties: email: type: string format: email description: The email address of the user. examples: - john.doe@example.com status: type: string enum: - active - inactive - pending - unknown description: > The membership status of this user in the organisation in the request URL. Only populated on org-scoped member endpoints; absent on global user endpoints. examples: - active identities: type: array items: type: object properties: id: type: string format: uuid description: The unique identifier for the identity. examples: - 39ce13b8-1116-416a-ad5f-3c5edfd44f53 platform: type: string description: The platform of the identity. examples: - multi_tenant meta: type: - object - 'null' additionalProperties: true description: Additional metadata for the identity. profile: type: object properties: work: type: object properties: occupation: type: string description: The occupation of the user. examples: - Site Manager cscs: type: string description: The CSCS card number of the user. examples: - CSC123456 eusr: type: string description: The EUSR card number of the user. examples: - EUR789123 start_date: type: string format: date description: The start date of the user's employment. examples: - '2020-03-01T00:00:00.000Z' personal: type: object properties: first_name: type: string description: The first name of the user. examples: - John last_name: type: string description: The last name of the user. examples: - Doe dob: type: string format: date description: The date of birth of the user. examples: - '1985-06-15T00:00:00.000Z' username: type: string description: The username of the user. examples: - johndoe contact: type: object properties: mobile: type: string description: The mobile number of the user. examples: - +44 7700 900123 landline: type: string description: The landline of the user. examples: - +44 20 7946 0958 address: type: object properties: number: type: string description: The house number of the user's address. default: '' examples: - '42' street: type: string description: The street of the user's address. examples: - High Street area: type: string description: The area of the user's address. examples: - Westminster town: type: string description: The town of the user's address. examples: - London county: type: string description: The county of the user's address. examples: - Greater London postcode: type: string description: The postcode of the user's address. examples: - SW1A 1AA country_code: type: string description: The country code of the user's address. examples: - GB what3words: type: string description: The what3words location of the user's address. examples: - filled.count.soap settings: type: object properties: preferred_language: type: string description: The preferred language of the user. default: en-GB examples: - en-GB timezone: type: string description: The timezone of the user. examples: - Europe/London UserMeta: type: object description: Metadata for a user properties: managed_type: type: string enum: - none - scim - organisation - unknown description: How this user is managed. UserRelationships: type: object description: Relationships for a user properties: organisations: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/OrganisationRelationship' teams: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/TeamRelationship' managing_organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' OrganisationRelationship: type: object description: Represents a relationship to an organisation required: - id - type properties: id: type: string format: uuid description: The unique identifier of the organisation type: type: string const: organisations TeamRelationship: type: object description: Represents a relationship to a team required: - id - type properties: id: type: string format: uuid description: The unique identifier of the team type: type: string const: teams securitySchemes: Session: description: | Session token for authentication. in: header name: X-Session-Token type: apiKey OAuth2: description: | OAuth2 token for authentication. flows: clientCredentials: scopes: {} tokenUrl: https://auth.ctrl-hub.com/oauth2/token type: oauth2 Cookie: description: | Cookie token for authentication. in: cookie name: ctrl_hub_session type: apiKey ````