> ## Documentation Index > Fetch the complete documentation index at: https://www.1password.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get a workflow run > Returns the run with the given ID for the workflow, including its context and step states, inside a one-item result page (empty if no run has that ID). The `variables` query parameter and the `Workflows.Runs.ReadSecrets` scope behave as for listing runs. **Required scope:** `Workflows.Runs.Read` (Read-only access to workflow runs) ## OpenAPI ````yaml /openapi/saas_manager_api.json get /api/workflows/v1/{workflowId}/runs/{runId} openapi: 3.0.4 info: title: SaaS Manager API description: >- By accessing or using 1Password Developer Tools, you agree to the [API and SDK Terms of Service](https://1password.com/legal/api-sdk-terms-of-service). --- The SaaS Manager public REST API lets you read and manage your applications, people, teams, contracts, devices, workflows and audit log programmatically. Resources are grouped by area (see the navigation). The conventions below apply across the whole API. ## Regions and base URL SaaS Manager is hosted in multiple regions. Pick the base URL for your tenant's region from the **Servers** dropdown — `https://app.trelica.com` (United States) or `https://eu.trelica.com` (Europe). Endpoint URLs throughout this reference use whichever server you select. ## Authentication Every request must send an `Authorization` header carrying an OAuth 2.0 access token, prefixed with `Bearer`: ``` Authorization: Bearer ``` Obtain a token using either the **Client Credentials** flow (machine-to-machine) or the **Authorization Code** flow (acting on behalf of a user). The scopes granted to your token determine which endpoints you may call — see [Scopes](#scopes). Access tokens expire. When a token is missing, invalid or expired you receive `401 Unauthorized`; inspect the `WWW-Authenticate` response header for detail, for example: ``` Bearer error="invalid_token", error_description="The token expired at '12/23/2020 10:27:15'" ``` If you used the Authorization Code flow with the `offline_access` scope, use your refresh token to obtain a new access token. A `403 Forbidden` means the token is valid but lacks the scope required by the endpoint. ## Dates and times Dates and date/times are sent and returned in [RFC 3339](https://tools.ietf.org/html/rfc3339) format (essentially ISO 8601), for example `2020-12-25` (midnight) or `2020-12-25T10:50:00Z`. Field names ending in `Dtm` carry a meaningful time component; field names ending in `Date` are date-only. ## Optional fields and null Responses omit fields that have no value — you will see the field absent rather than returned as `null`. When creating or replacing a resource (`PUT`), any field you omit is cleared. With `PATCH`, omitting a field leaves it unchanged, whereas sending it as `null` clears it. ## Pagination List endpoints are paginated and return at most 100 results by default. Request a different upper bound with the `limit` query parameter (maximum 1000) — you may receive fewer than requested. Request the next page with the `after` query parameter, passing the opaque cursor token that SaaS Manager supplies. The response's `next` field (and the `link` response header, `rel="next"`) contains the full URL for the next page: ```json { "next": "https://app.trelica.com/api/people/v1?after=&limit=100", "results": [ { /* ... */ } ] } ``` Keep requesting pages until no further results are returned. (User data exposed over SCIM uses the SCIM `startIndex`/`count` pagination scheme instead.) ## Filtering Many list endpoints accept a `filter` query parameter (URL-encoded) based on the [SCIM filtering specification](https://tools.ietf.org/html/rfc7644#section-3.4.2.2). A filter is one or more expressions — an attribute name, an operator, and an optional value — combined with `and`, `or`, `not`, and grouped with parentheses. Attribute names match the JSON returned and may use dot notation for nested attributes (e.g. `createdBy.email`). For an attribute that is an **array of objects**, put a sub-expression in brackets — the item matches when *any* element satisfies it: `teams[name eq "Developers"]` or `teams[id eq "5f8d0a1b2c3d4e5f60718293"]`. Values are strings (double-quoted), integers, dates (double-quoted, RFC 3339) or booleans. Some list endpoints also accept a free-text `q` parameter that searches the resource's displayable fields. Soft-deleted entities are excluded by default; include them with a filter that references `deleted` (e.g. `filter=deleted eq true`). | Operator | Meaning | Behaviour | |----------|---------|-----------| | `eq` | equal | Attribute value is identical to the operator value | | `ne` | not equal | Attribute value differs from the operator value | | `co` | contains | Attribute value contains the operator value text | | `sw` | starts with | Attribute value starts with the operator value text | | `ew` | ends with | Attribute value ends with the operator value text | | `pr` | present | Attribute has a non-empty / non-null value | | `gt` | greater than | Attribute value is greater than the operator value | | `ge` | greater than or equal | Attribute value is greater than or equal to the operator value | | `lt` | less than | Attribute value is less than the operator value | | `le` | less than or equal | Attribute value is less than or equal to the operator value | For `gt`/`ge`/`lt`/`le`, strings compare lexicographically, dates chronologically and numbers numerically. Each list endpoint documents the fields you can filter on. **Examples** | Filter | Result | |--------|--------| | `firstName sw "Jan"` | People whose first name starts with "Jan" | | `teams[name eq "Developers"]` | People in the team called Developers | | `not (leavingDate pr)` | People with no leaving date | | `lastModifiedDtm ge "2021-06-01"` | Records modified on or after 1 June 2021 | ## Errors A `400 Bad Request` indicates a problem with your request. The body is a problem-details object: `errors` maps each offending field to its messages, with `title`, `status`, a `type` URL, and an `extensions.traceId` for correlation: ```json { "errors": { "leavingDate": [ "Error converting value \"2020-40-40\" ..." ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "extensions": { "traceId": "00-91e4405b...-00" } } ``` You should not normally see `500 Internal Server Error`. If you do, the body is a generic message — please contact [saasmanager@1password.com](mailto:saasmanager@1password.com) with details of the request so we can investigate. ## Scopes Scopes define what an API app may do. Following security best practice, grant only the scopes you need. Each endpoint documents the scope(s) it requires. | Scope | Description | |-------|-------------| | `Apps.Read` | Read-only access to applications | | `Apps.Users.Read` | Read-only access to application accounts | | `Apps.Write` | Write access to applications | | `Assets.Read` | Read-only access to devices | | `Assets.Write` | Write access to devices | | `AuditLog.Read` | Read-only access to the audit log | | `Contracts.Read` | Read-only access to contracts | | `Contracts.Write` | Write access to contracts | | `People.Read` | Read-only access to people and teams | | `People.Write` | Write access to people and teams | | `Users.Read` | Read-only access to users with access to SaaS Manager | | `Users.Write` | Write access to users with access to SaaS Manager | | `Workflows.Read` | Read-only access to workflow definitions | | `Workflows.Runs.Read` | Read-only access to workflow runs | | `Workflows.Runs.Execute` | Execute workflow run actions | | `Workflows.Runs.ReadSecrets` | Read workflow run secrets | | `offline_access` | Issue a refresh token alongside the access token (Authorization Code flow) | contact: name: 1Password SaaS Manager Support email: saasmanager@1password.com version: v1 servers: - url: https://app.trelica.com description: United States - url: https://eu.trelica.com description: Europe security: [] tags: - name: Authentication description: >- Obtain an OAuth 2.0 access token. Use the Client Credentials flow for machine-to-machine access, or the Authorization Code flow to act on behalf of a user. - name: Applications description: >- List, search and manage applications, and list the accounts (users) on an application. - name: People description: List, search and manage the people in your organization. - name: Teams description: List and manage teams and the team hierarchy. - name: Contracts description: List and manage contracts. - name: Devices description: List and manage devices. The endpoints live under `/api/assets`. - name: Workflows description: >- List workflows (with their triggers and steps), list their runs, and fire signals on steps that are waiting for input. - name: Audit log description: >- Read your organization's audit log: a continuous, filterable stream of events. - name: SCIM description: >- Provision and manage users via the SCIM 2.0 protocol (RFC 7644). These endpoints follow the SCIM standard rather than the conventions used by the rest of the SaaS Manager API: they use `startIndex`/`count` paging, return a SCIM `ListResponse` envelope, identify schemas with `urn:` URIs, and exchange `application/scim+json`. The `ResourceTypes` endpoints support SCIM discovery (RFC 7643). paths: /api/workflows/v1/{workflowId}/runs/{runId}: get: tags: - Workflows summary: Get a workflow run description: >- Returns the run with the given ID for the workflow, including its context and step states, inside a one-item result page (empty if no run has that ID). The `variables` query parameter and the `Workflows.Runs.ReadSecrets` scope behave as for listing runs. **Required scope:** `Workflows.Runs.Read` (Read-only access to workflow runs) parameters: - name: workflowId in: path required: true schema: type: string - name: runId in: path required: true schema: type: string - name: variables in: query description: >- A comma-separated list of workflow variable IDs whose values should be included in each run's context. Values are omitted unless requested here. Reading a secret (password) variable additionally requires the `Workflows.Runs.ReadSecrets` scope. schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/WorkflowRunPage' example: next: >- https://app.trelica.com/api/workflows/v1/b7288c2c64f779e28024ea0e/runs?after=eyJpZCI6IjY2MmE4YzExZjA3YmEwYWY5YTI1Yzg2MCJ9&limit=100 results: - id: 649454cc391d7e83ae7a0aa5 name: Shirley Lane status: Completed createdBy: userId: a9b8c7d6-e5f4-43a2-b1c0-9a8b7c6d5e4f name: Samira Johnson email: samira.johnson@example.com createdDtm: '2023-06-22T14:03:56.248Z' deleted: false lastModifiedDtm: '2023-06-22T14:04:16.157Z' context: person: id: 67aa6cdf421044b49ad1d6dfded7bf21 name: Shirley Lane firstName: Shirley lastName: Lane email: shirley.lane@example.com employeeId: E001529 location: Cambridge, UK jobTitle: Content Lead team: Web site leavingDate: '2023-05-25T00:00:00Z' customFields: personalemail: null trigger: id: 54d9783a47e694183a270549 type: PersonLeaves status: Completed completed: dtm: '2023-06-22T14:04:15.021Z' nextStepIds: - 54d9783a47e694183a27054a newContext: person: id: 67aa6cdf421044b49ad1d6dfded7bf21 name: Shirley Lane firstName: Shirley lastName: Lane email: shirley.lane@example.com employeeId: E001529 location: Cambridge, UK jobTitle: Content Lead team: Web site leavingDate: '2023-05-25T00:00:00Z' customFields: personalemail: null steps: - id: 54d9783a47e694183a27054a type: OffboardPersonApps name: Offboard person from apps status: Completed completed: dtm: '2023-06-22T14:04:16.149Z' nextStepIds: [] - id: 662a8c11f07ba0af9a25c860 name: Stephanie Mason status: Waiting createdBy: userId: 7cbf8b34-a321-43f0-8c8f-275b41e30b14 name: System email: admin@example.com createdDtm: '2024-04-25T17:00:01.207Z' deleted: false lastModifiedDtm: '2024-04-25T17:00:01.375Z' context: person: id: 0ad0090d2f27407ba1312883e805b123 name: Stephanie Mason firstName: Stephanie lastName: Mason email: stephanie.mason@example.com employeeId: E001557 location: Palo Alto, CA jobTitle: Accounts Receivable Executive team: Accounts Receivable startDate: '2022-06-04T00:00:00Z' leavingDate: '2024-04-07T00:00:00Z' customFields: personalemail: null trigger: id: 54d9783a47e694183a270549 type: PersonLeaves status: Waiting waiting: dtm: '2024-04-25T17:00:01.326Z' steps: [] '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' example: type: about:blank title: One or more validation errors occurred. status: 400 detail: >- The request body failed validation. See errors for the offending fields. errors: email: - The email field is required. traceId: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01 '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' example: type: about:blank title: Not found. status: 404 detail: >- The requested resource does not exist or you do not have access to it. traceId: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01 security: - oauth2: - Workflows.Runs.Read components: schemas: WorkflowRunPage: type: object properties: next: type: string description: >- The URL of the next page of results. Absent when there are no more results. results: type: array items: $ref: '#/components/schemas/WorkflowRun' description: The page of results. additionalProperties: false Error: type: object properties: type: type: string description: A URI reference identifying the problem type. title: type: string description: A short, human-readable summary of the problem. status: type: integer description: The HTTP status code. format: int32 detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem. errors: type: object additionalProperties: type: array items: type: string description: Validation errors keyed by field name. Present on 400 responses. traceId: type: string description: >- A trace identifier for correlating the error with SaaS Manager support. additionalProperties: false description: An error response (RFC 7807 problem details). WorkflowRun: type: object properties: id: type: string description: The run's unique ID. name: type: string description: The run's name. status: enum: - InProgress - Waiting - Failed - Completed - Terminated type: string description: The run's status. createdBy: allOf: - $ref: '#/components/schemas/UserInfoFlow' description: The user who created (started) the run. createdDtm: type: string description: When the run was created (UTC). format: date-time deleted: type: boolean description: >- Whether the run has been deleted. Deleted runs are excluded unless the filter references this field. lastModifiedDtm: type: string description: When the run was last modified (UTC). format: date-time context: allOf: - $ref: '#/components/schemas/FlowItemScope' description: >- The context (the people, applications, accounts, task and variables) the run operates on. waitingUntilDtm: type: string description: If the run is waiting, the time it is waiting until (UTC). format: date-time trigger: allOf: - $ref: '#/components/schemas/WorkflowRunStep' description: The trigger step's state for this run. steps: type: array items: $ref: '#/components/schemas/WorkflowRunStep' description: The state of each step in the run. additionalProperties: false UserInfoFlow: type: object properties: userId: type: string name: type: string email: type: string additionalProperties: false FlowItemScope: type: object properties: person: allOf: - $ref: '#/components/schemas/FlowPerson' description: The single person the run operates on, if any. people: type: array items: $ref: '#/components/schemas/FlowPerson' description: The set of people the run operates on, if any. app: allOf: - $ref: '#/components/schemas/FlowApp' description: The single application the run operates on, if any. apps: type: array items: $ref: '#/components/schemas/FlowApp' description: The set of applications the run operates on, if any. appUser: allOf: - $ref: '#/components/schemas/FlowAppUser' description: The single application account the run operates on, if any. appUsers: type: array items: $ref: '#/components/schemas/FlowAppUser' description: The set of application accounts the run operates on, if any. task: allOf: - $ref: '#/components/schemas/FlowTask' description: The task the run operates on, if any. variables: type: object additionalProperties: {} description: >- The requested workflow variable values, keyed by variable ID. Only returned for variables named in the "variables" query parameter. additionalProperties: false WorkflowRunStep: type: object properties: id: type: string description: The step's unique ID. type: type: string description: The step type, e.g. "SendEmail", "Wait", "SetAppStatus". name: type: string description: The step's name. status: enum: - NotStarted - InProgress - Waiting - Failed - Completed - Skipped - SkippedWithError type: string description: The step's status. completed: allOf: - $ref: '#/components/schemas/StepCompletedResult' description: Present when the step has completed; details of the result. waiting: allOf: - $ref: '#/components/schemas/StepWaitingResult' description: Present when the step is waiting; details of what it is waiting for. failed: allOf: - $ref: '#/components/schemas/StepFailedResult' description: Present when the step has failed; details of the failure. additionalProperties: false FlowPerson: type: object properties: id: type: string description: The person's unique ID. name: type: string description: The person's full name. firstName: type: string description: The person's first name. lastName: type: string description: The person's last name. email: type: string description: The person's email address. employeeId: type: string description: The person's employee ID. location: type: string description: The person's location. jobTitle: type: string description: The person's job title. team: type: string description: The person's team. startDate: type: string description: The person's start date. format: date-time leavingDate: type: string description: The person's leaving date. format: date-time lineManager: allOf: - $ref: '#/components/schemas/PersonInfoFlow' description: The person's line manager. customFields: type: object additionalProperties: {} description: Custom field values, keyed by the field's name. additionalProperties: false FlowApp: type: object properties: id: type: string description: The application's unique ID. name: type: string description: The application's name. additionalProperties: false FlowAppUser: type: object properties: id: type: string description: The application account's unique ID. appId: type: string description: The ID of the application the account belongs to. appName: type: string description: The name of the application the account belongs to. appInstanceName: type: string description: The instance name of the application, if it has one. userId: type: string description: The ID of the SaaS Manager user the account is matched to. userName: type: string description: The account's user name. userEmail: type: string description: The account's email address. primaryExternalId: type: string description: The account's primary external ID, as held by the application. primaryExternalEmail: type: string description: >- The account's primary external email address, as held by the application. additionalProperties: false FlowTask: type: object properties: id: type: string description: The task's unique ID. taskTypeId: type: string description: The ID of the task's type. appliesToType: type: string description: >- What the task applies to, e.g. "Vendor", "Application", "User", "Nothing". appliesToItemId: type: string description: The ID of the item the task applies to. status: type: string description: The task's status. appliesToItemName: type: string description: The name of the item the task applies to. title: type: string description: The task's title. description: type: string description: The task's description. owner: allOf: - $ref: '#/components/schemas/PersonInfoFlow' description: The task's owner. assignedTo: allOf: - $ref: '#/components/schemas/PersonInfoFlow' description: The person the task is assigned to. dueDate: type: string description: The task's due date. format: date-time additionalProperties: false StepCompletedResult: type: object properties: dtm: type: string description: When the step completed (UTC). format: date-time nextStepIds: type: array items: type: string description: The IDs of the steps that run next. newContext: allOf: - $ref: '#/components/schemas/FlowItemScope' description: The run context after the step completed, if the step changed it. additionalProperties: false StepWaitingResult: type: object properties: dtm: type: string description: When the step started waiting (UTC). format: date-time until: type: string description: If the step is waiting on a timer, when it will resume (UTC). format: date-time actions: type: array items: $ref: '#/components/schemas/StepWaitingAction' description: The signals that can be fired on this step to make the run continue. additionalProperties: false StepFailedResult: type: object properties: dtm: type: string description: When the step failed (UTC). format: date-time message: type: string description: The failure message. additionalProperties: false PersonInfoFlow: type: object properties: id: type: string personType: allOf: - $ref: '#/components/schemas/PersonValueType' name: type: string email: type: string additionalProperties: false StepWaitingAction: type: object properties: name: type: string description: The signal's name, e.g. "Approve" or "Reject". href: type: string description: >- The URL to POST to in order to fire this signal and continue the run. additionalProperties: false PersonValueType: enum: - Contact - User type: string securitySchemes: oauth2: type: oauth2 description: >- OAuth 2.0. Obtain an access token via the Client Credentials or Authorization Code flow, then send it as `Authorization: Bearer `. flows: clientCredentials: tokenUrl: https://app.trelica.com/connect/token scopes: Apps.Read: Read-only access to applications Apps.Users.Read: Read-only access to application accounts Apps.Write: Write access to applications Assets.Read: Read-only access to devices Assets.Write: Write access to devices AuditLog.Read: Read-only access to the audit log Contracts.Read: Read-only access to contracts Contracts.Write: Write access to contracts People.Read: Read-only access to people and teams People.Write: Write access to people and teams Users.Read: Read-only access to users with access to SaaS Manager Users.Write: Write access to users with access to SaaS Manager Workflows.Read: Read-only access to workflow definitions Workflows.Runs.Read: Read-only access to workflow runs Workflows.Runs.Execute: Execute workflow run actions Workflows.Runs.ReadSecrets: Read workflow run secrets offline_access: >- Issue a refresh token alongside the access token (Authorization Code flow) authorizationCode: authorizationUrl: https://app.trelica.com/connect/authorize tokenUrl: https://app.trelica.com/connect/token scopes: Apps.Read: Read-only access to applications Apps.Users.Read: Read-only access to application accounts Apps.Write: Write access to applications Assets.Read: Read-only access to devices Assets.Write: Write access to devices AuditLog.Read: Read-only access to the audit log Contracts.Read: Read-only access to contracts Contracts.Write: Write access to contracts People.Read: Read-only access to people and teams People.Write: Write access to people and teams Users.Read: Read-only access to users with access to SaaS Manager Users.Write: Write access to users with access to SaaS Manager Workflows.Read: Read-only access to workflow definitions Workflows.Runs.Read: Read-only access to workflow runs Workflows.Runs.Execute: Execute workflow run actions Workflows.Runs.ReadSecrets: Read workflow run secrets offline_access: >- Issue a refresh token alongside the access token (Authorization Code flow) ```` ## Related topics - [Get a workflow](/api-reference/workflows/get-a-workflow.md) - [List workflow runs](/api-reference/workflows/list-workflow-runs.md) - [List workflows](/api-reference/workflows/list-workflows.md)