> ## Documentation Index > Fetch the complete documentation index at: https://docs.getmodus.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a workflow run > Returns a single run — live state for in-progress runs, or the full history for completed runs. **Requires:** `workflows:invoke` ## OpenAPI ````yaml https://api.getmodus.com/openapi.json get /api/v1/workflows/{id}/runs/{runId} openapi: 3.0.3 info: title: Modus Public API version: 1.0.0 servers: [] security: - bearerAuth: [] tags: - name: Scopes description: Create, configure, deploy, and manage scopes. - name: Scopes · Conversations description: Read scope conversation threads. - name: Scopes · Supervision description: Scope supervision sub-resource. - name: Scopes · Memories description: Long-term memory stored per scope. - name: Scopes · Chat description: Chat with a published scope. - name: Scopes · Context description: Compose a scope’s context without an LLM call. - name: Modus · Chat description: Chat with Modus — your org-wide assistant. - name: Modus · Conversations description: Read Modus and cross-scope conversation threads. - name: Modus · Context description: Compose full-environment context without an LLM call. - name: Workflows description: Create, configure, deploy, and manage workflows. - name: Workflows · Runs description: Inspect workflow run history. - name: Workflows · Interfaces description: Slack / MCP / Teams interface management. - name: Connections description: Read connected integrations. - name: Tools description: Catalog of tools/integrations a scope can select in its toolset. - name: Suggestions description: Approved suggested questions and first-party suggestion usage events. - name: Context description: Create and manage organization context items. - name: Usage description: Organization LLM usage reporting. - name: Users description: Organization and membership management. - name: Runs · Streaming description: 'Run lifecycle: stream, poll, resume, interrupt, and cancel executions.' - name: Scopes · Runs description: Run a published or draft scope. - name: Modus · Runs description: Run the Modus home agent. paths: /api/v1/workflows/{id}/runs/{runId}: get: tags: - Workflows · Runs summary: Get a workflow run description: >- Returns a single run — live state for in-progress runs, or the full history for completed runs. **Requires:** `workflows:invoke` operationId: WorkflowRunsController_get parameters: - name: id required: true in: path description: Numeric workflow id. schema: example: 42 type: number - name: runId required: true in: path description: Run identifier. schema: example: wf_42_run_1 type: string - name: temporalRunId required: false in: query schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/GetAutomationRunResponseDto' '400': description: >- Malformed request — invalid query parameters or request body (`code: BAD_REQUEST`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: BAD_REQUEST status: INVALID_ARGUMENT message: Invalid value for query parameter `pageSize`. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '401': description: 'Missing, invalid, or expired access token (`code: UNAUTHORIZED`).' content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: UNAUTHORIZED status: UNAUTHENTICATED message: Missing or invalid access token. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '403': description: >- Authenticated, but the token lacks a required scope (`code: FORBIDDEN`). The missing scopes are listed in `info`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: FORBIDDEN status: PERMISSION_DENIED message: Missing required scope(s) for this operation. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS info: missing: - '404': description: >- The resource does not exist, or you do not have access to it (`code: NOT_FOUND`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: NOT_FOUND status: NOT_FOUND message: Resource not found. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '500': description: 'An unexpected server error occurred (`code: INTERNAL_ERROR`).' content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: INTERNAL_ERROR status: INTERNAL message: An unexpected error occurred. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS security: - bearerAuth: [] servers: - url: https://api.getmodus.com components: schemas: GetAutomationRunResponseDto: type: object properties: id: type: string description: Composite run identifier (`workflowId:temporalRunId`). example: wf_42_run_1:11111111-2222-3333-4444-555555555555 workflowId: type: string description: Workflow run identifier. example: wf_42_run_1 temporalRunId: type: string description: Run identifier; a workflow may have multiple runs after a retry. agentId: type: number description: Parent workflow id. example: 42 agentName: type: string description: Snapshot of the workflow name at the time the run was indexed. example: Daily Sales Report agentType: description: Workflow type. example: task allOf: - $ref: '#/components/schemas/AgentType' status: type: string description: >- Run status (running / awaiting_human / completed / error / cancelled). example: completed triggerType: type: string description: >- Trigger type for the run (schedule / webhook / api / slack / manual). startedAt: type: string description: ISO-8601 start timestamp. endedAt: type: string description: ISO-8601 end timestamp; absent for in-flight runs. durationMs: type: number description: Duration in milliseconds (when end timestamp is known). summary: type: string description: Short human-readable summary of the run outcome. pendingApproval: type: object description: >- Pending approval payload (only present when status is awaiting_human). additionalProperties: true statusReason: type: string description: >- Display-only signal that the workflow closed for a non-success reason. enum: - approval_timeout source: description: >- Where the payload was read from. `live-query` = the run is still in progress; `history` = a completed run. allOf: - $ref: '#/components/schemas/AutomationRunSource' taskResult: type: object description: >- Final result of a `task`-typed workflow run. Free-form (depends on the workflow). additionalProperties: true taskError: type: string description: Error message for a failed `task`-typed workflow run. workflowNodes: type: array description: Per-node state for a `workflow`-typed workflow run. items: type: object additionalProperties: true historyUnavailableReason: type: string description: >- Set when history was unavailable; `source` will be `live-query` in that case. required: - id - workflowId - agentId - agentName - agentType - status - source ErrorResponseDto: type: object properties: error: $ref: '#/components/schemas/ErrorEnvelopeDto' required: - error AgentType: type: string enum: - task - workflow description: >- Type of workflow. `task` = single-step scope orchestration; `workflow` = multi-step graph. AutomationRunSource: type: string enum: - live-query - history description: >- Where the payload was read from. `live-query` = the run is still in progress; `history` = a completed run. ErrorEnvelopeDto: type: object properties: code: description: Modus-specific machine code. allOf: - $ref: '#/components/schemas/ApiErrorCode' status: description: Canonical status string for the error. allOf: - $ref: '#/components/schemas/ApiErrorStatus' message: type: string example: Skill was not found or you lack permission. requestId: type: string example: req_01HQ7K8ABCDEFGHIJKLMNOPQRS info: type: object description: >- Optional domain-specific context. Shape varies per endpoint — see the operation's error response examples. additionalProperties: true example: skillId: sk_abc123 required: - code - status - message - requestId ApiErrorCode: type: string enum: - VALIDATION - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR description: Modus-specific machine code. ApiErrorStatus: type: string enum: - INVALID_ARGUMENT - UNAUTHENTICATED - PERMISSION_DENIED - NOT_FOUND - ALREADY_EXISTS - RESOURCE_EXHAUSTED - INTERNAL description: Canonical status string for the error. securitySchemes: bearerAuth: scheme: bearer bearerFormat: Modus PAT (modus___) or OAuth 2.1 access token type: http description: >- A Modus personal access token (`modus___`) or an OAuth 2.1 access token, sent as `Authorization: Bearer `. ````