> ## Documentation Index
> Fetch the complete documentation index at: https://docs.file.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get workflow result groups by unique identifiers
> Retrieve workflow execution result groups for one or more execution group unique identifiers (e.g. folder or subfolder ids).
Query parameters:
- executionGroupUniqueIdentifiers (required): Comma-separated list of unique identifiers
- workflowStepIds (optional): Comma-separated workflow step ObjectIds to filter results
Each result group includes structural fields and, when present, an assessment summary with overallPassed, assessmentStatus, rejectionReason, and per-rule pass/fail.
Retrieve workflow execution result groups for one or more execution group unique
identifiers — typically folder or subfolder ids. Use this to read the outcome of
a workflow run, including its assessment summary.
## Request Parameters
### Query Parameters
| Parameter | Type | Required | Description |
| ------------------------------- | ------ | -------- | ------------------------------------------------------------------------- |
| executionGroupUniqueIdentifiers | string | Yes | Comma-separated execution group unique identifiers (folder/subfolder ids) |
| workflowStepIds | string | No | Comma-separated workflow step ObjectIds to filter the results by |
Examples use the default base URL, `https://api.orion.file.ai/prod/v1`. If
your workspace is on an instance-specific host, swap the hostname and change
nothing else — see [Switching between
instances](/docs-api/api-intro#switching-between-instances).
```bash theme={null}
curl -X GET "https://api.orion.file.ai/prod/v1/workflows/result-groups?executionGroupUniqueIdentifiers=folder-abc-123,folder-def-456" \
-H "x-api-key: YOUR_API_KEY"
```
## Response Structure
### Result Group Object
| Field | Type | Description |
| ------------------------------ | ------ | --------------------------------------------------------------- |
| id | string | Unique result group identifier |
| workflowId | string | The workflow this result belongs to |
| workflowStepId | string | The workflow step that produced this result |
| workflowStepName | string | Step name (nullable) |
| executionGroupName | string | Human-readable group name, e.g. the folder name (nullable) |
| executionGroupKey | string | The key the group was formed on, e.g. `$contactName` (nullable) |
| executionGroupUniqueIdentifier | string | The identifier you queried on (nullable) |
| status | string | Result group status (e.g. `active`) |
| assessment | object | Assessment summary, when the step produced one (nullable) |
| createdAt | string | ISO 8601 timestamp of creation |
| updatedAt | string | ISO 8601 timestamp of last update |
### Assessment Summary
| Field | Type | Description |
| ------------------- | ------- | ------------------------------------------------------------- |
| overallPassed | boolean | Whether the group passed overall |
| assessmentStatus | string | Overall status, e.g. `PASSED` |
| rejectionReason | string | Why the group was rejected, when applicable (nullable) |
| checklistResults | array | Per-rule checklist outcomes, each with `passed` and `clauses` |
| withinSchemaResults | array | Per-rule results evaluated within a single schema |
| crossSchemaResults | array | Per-rule results evaluated across schemas |
## Example Response
```json theme={null}
{
"resultGroups": [
{
"id": "68218006ebc72170fdb221f7",
"workflowId": "68218006ebc72170fdb221f8",
"workflowStepId": "68218006ebc72170fdb221f9",
"workflowStepName": "Assessment",
"executionGroupName": "Acme Corp",
"executionGroupKey": "$contactName",
"executionGroupUniqueIdentifier": "folder-abc-123",
"status": "active",
"createdAt": "2024-10-18T16:45:50.064Z",
"updatedAt": "2025-05-15T09:23:31.609Z",
"assessment": {
"overallPassed": true,
"assessmentStatus": "PASSED",
"checklistResults": [
{
"ruleSearchId": "rule-1",
"ruleName": "Invoice present",
"passed": true,
"clauses": [
{ "blueprintName": "Invoice", "matched": true },
{ "blueprintName": "Purchase Order", "matched": true }
]
}
],
"withinSchemaResults": [
{
"ruleSearchId": "rule-2",
"blueprintId": "671290be60a313d55c800016",
"blueprintName": "Invoice",
"overallStatus": "VERIFIED"
}
],
"crossSchemaResults": [
{ "ruleSearchId": "rule-3", "overallStatus": "UNVERIFIED" }
]
}
}
]
}
```
`assessment` is only present for steps that run an assessment. Steps of other
types return the structural fields with `assessment` set to `null`.
## Errors
A `422` is returned when `executionGroupUniqueIdentifiers` or `workflowStepIds`
are malformed. See [Error responses](/docs-api/api-errors).
## OpenAPI
````yaml get /prod/v1/workflows/result-groups
openapi: 3.0.0
info:
title: Public API
description: >-
### Welcome to fileAI’s Public API Documentation.
This API allows users to check the health of the system, upload and manage
files, and manage AI Schemas.
Should you have any questions, please reach out to fileAI via the “Contact a
Developer” link below.
[Contact a Developer](mailto:support@file.ai)
### Prerequisites
Before using our API, please ensure you complete the following prerequisites
- You must have a fileAI account. Sign up or login
[here](https://orion.file.ai/en/sign-up)
- You must have an API Key. After creating your fileAI account, you can
generate your API Key. Refer to the Authentication section below for more
details.
### Authentication
All API requests require an API key for authentication.
- To obtain your API key, please log in to your fileAI account and navigate
to Project Settings in your dashboard
- Keep your API key secure and do not share it publicly.
### How to Use Your API Key
Once you have your API key:
- Click the Authorize button on the top-right of this page
- Enter your API Key under Value
- Click Authorize to start making authenticated requests directly from the
documentation
version: '1.0'
contact: {}
servers:
- url: https://api.orion.file.ai
description: Default. Use this unless your workspace is on an instance.
- url: https://api.orion.{instance}.file.ai
description: Instance-specific host.
variables:
instance:
default: au
enum:
- au
- sg
- jp
description: >-
Instance hosting your workspace: au (Australia), sg (Singapore), jp
(Japan).
security: []
tags:
- name: Public API V1
paths:
/prod/v1/workflows/result-groups:
get:
tags:
- Public API V1
summary: Get workflow result groups by unique identifiers
description: >-
Retrieve workflow execution result groups for one or more execution
group unique identifiers (e.g. folder or subfolder ids).
Query parameters:
- executionGroupUniqueIdentifiers (required): Comma-separated list of
unique identifiers
- workflowStepIds (optional): Comma-separated workflow step ObjectIds to
filter results
Each result group includes structural fields and, when present, an
assessment summary with overallPassed, assessmentStatus,
rejectionReason, and per-rule pass/fail.
operationId: PublicAPIController_getManyWorkflowResultGroups
parameters:
- name: executionGroupUniqueIdentifiers
required: true
in: query
description: >-
Comma-separated execution group unique identifiers (folder/subfolder
ids)
schema:
example: folder-abc-123,folder-def-456
type: string
- name: workflowStepIds
required: false
in: query
description: Optional comma-separated workflow step ObjectIds to filter by
schema:
example: 649e2d2d2d2d2d2d2d2d2d2e,649e2d2d2d2d2d2d2d2d2d2f
type: string
responses:
'200':
description: The workflow result groups are retrieved
content:
application/json:
example:
resultGroups:
- id: 68218006ebc72170fdb221f7
workflowId: 68218006ebc72170fdb221f8
workflowStepId: 68218006ebc72170fdb221f9
workflowStepName: Assessment
executionGroupName: Acme Corp
executionGroupKey: $contactName
executionGroupUniqueIdentifier: folder-abc-123
status: active
createdAt: '2024-10-18T16:45:50.064Z'
updatedAt: '2025-05-15T09:23:31.609Z'
assessment:
overallPassed: true
assessmentStatus: PASSED
checklistResults:
- ruleSearchId: rule-1
ruleName: Invoice present
passed: true
clauses:
- blueprintName: Invoice
matched: true
- blueprintName: Purchase Order
matched: true
withinSchemaResults:
- ruleSearchId: rule-2
blueprintId: 671290be60a313d55c800016
blueprintName: Invoice
overallStatus: VERIFIED
crossSchemaResults:
- ruleSearchId: rule-3
overallStatus: UNVERIFIED
schema:
type: object
properties:
resultGroups:
type: array
items:
type: object
properties:
id:
type: string
workflowId:
type: string
workflowStepId:
type: string
workflowStepName:
type: string
nullable: true
executionGroupName:
type: string
nullable: true
executionGroupKey:
type: string
nullable: true
executionGroupUniqueIdentifier:
type: string
nullable: true
status:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
assessment:
type: object
nullable: true
properties:
overallPassed:
type: boolean
assessmentStatus:
type: string
rejectionReason:
type: string
nullable: true
checklistResults:
type: array
items:
type: object
withinSchemaResults:
type: array
items:
type: object
crossSchemaResults:
type: array
items:
type: object
'401':
description: Missing or invalid API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'403':
description: Read-only or inactive API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'404':
description: Resource not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'422':
description: Invalid executionGroupUniqueIdentifiers or workflowStepIds
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
example:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid executionGroupUniqueIdentifiers.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid executionGroupUniqueIdentifiers.
error: Unprocessable Entity
statusCode: 422
'429':
description: Rate limit exceeded.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'500':
description: Unexpected internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
security:
- x-api-key: []
components:
schemas:
ProblemDetailsDto:
type: object
properties:
type:
type: string
description: A URI identifying the problem type.
example: https://errors.file.ai/validation-failed
title:
type: string
description: Stable, human-readable summary of the problem type.
example: Validation failed
status:
type: number
description: HTTP status code.
example: 422
detail:
type: string
description: Human-readable explanation specific to this occurrence.
example: One or more fields are invalid.
instance:
type: string
description: URI reference for this occurrence (the request path).
example: /v1/files/upload
code:
type: string
description: Stable machine-readable error code.
example: VALIDATION_FAILED
requestId:
type: string
description: Correlation id for this request.
example: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors:
description: Field-level violations (validation only).
type: array
items:
$ref: '#/components/schemas/ProblemErrorItemDto'
retryAfter:
type: number
description: Seconds until the client may retry (present on 429 only).
example: 42
message:
type: string
description: Legacy key (deprecated — use `detail`/`title`).
example: Validation failed
error:
type: string
description: Legacy key (deprecated — use `title`).
example: Unprocessable Entity
statusCode:
type: number
description: Legacy key (deprecated — use `status`).
example: 422
required:
- type
- title
- status
- detail
- instance
- code
- requestId
- errors
- message
- error
- statusCode
ProblemErrorItemDto:
type: object
properties:
code:
type: string
example: REQUIRED
detail:
type: string
example: must not be empty
pointer:
type: string
description: JSON Pointer to the offending body field.
example: '#/fileName'
parameter:
type: string
description: Name of the offending query/header parameter.
example: limit
required:
- code
- detail
securitySchemes:
x-api-key:
type: apiKey
in: header
name: x-api-key
description: API key for authentication
````