> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Get workflow instance

GET https://api-d.docusign.com/v1/accounts/{accountId}/workflows/{workflowId}/instances/{instanceId}

This operation retrieves a single Workflow Builder workflow instance by its unique identifier (`id`).
It returns the primary details of the workflow instance, including its name, status,
starting information, and other metadata.

The response provides key details that help users understand the current state of the workflow
instance, when it was started, and who initiated it. Additional metadata is included to support
auditing and reporting within the system.

### Use Cases:
- Getting the details of a specific workflow instance for further processing or review
- Monitoring the status of a running workflow instance to determine completion or cancellation
- Accessing metadata for auditing, logging, or reporting on a single workflow instance

### Key Features:
- **Single Workflow Instance**: Provides direct access to a specific workflow instance by `id`
- **Detailed Status Information**: Includes the workflow's start and end times, status, and other lifecycle timestamps
- **Metadata for Tracking**: Useful metadata like who initiated the workflow (`started_by`) and versioning details
- **Future-Proof**: Designed to be extensible if additional fields or nested information are required over time


Reference: https://developers.docusign.com/docs/workflow-builder-api/reference/workflowbuilder/workflowinstancemanagement/getworkflowinstance

## Authentication

- `Authorization` header (bearer token, required) — OAuth2 authentication. - Demo: - authorizationUrl: https://account-d.docusign.com/oauth/auth - tokenUrl: https://account-d.docusign.com/oauth/token - Production: - authorizationUrl: https://account.docusign.com/oauth/auth - tokenUrl: https://account.docusign.com/oauth/token

## Servers

- `https://api-d.docusign.com` (Demo, default)
- `https://api.docusign.com` (Production)

## Request

### Path parameters

- `accountId` (string, required) — The unique identifier of the account.
- `workflowId` (string, required) — A universally unique identifier (UUID) in standard 8-4-4-4-12 format.
- `instanceId` (string, required) — Unique identifier for the workflow instance

## Response

### 200

Successful response containing the workflow instance details

- `id` (string, optional) — Unique identifier for the workflow instance
- `name` (string, optional) — Human-readable name for the workflow instance
- `workflow_status` (string, optional) — Current status of the workflow (e.g. In Progress, Completed, Canceled)
- `template_id` (string, optional) — Identifier linking this instance to a workflow template
- `account_id` (string, optional) — Account under which this workflow instance was initiated
- `started_at` (datetime, optional) — Date and time when the workflow was started
- `started_by` (string, optional) — User or system identifier that started this workflow
- `started_by_name` (string, optional) — Display name of the user who started this workflow
- `started_by_role` (string, optional) — Role of the user who started this workflow (e.g. Preparer)
- `ended_at` (datetime, optional, nullable) — Date and time when the workflow completed
- `expires_at` (datetime, optional, nullable) — Date and time after which the workflow expires
- `last_modified_at` (datetime, optional) — Date and time when the workflow instance was last modified
- `canceled_at` (datetime, optional, nullable) — Date and time when the workflow was canceled (if applicable)
- `canceled_by` (string, optional, nullable) — User or system identifier that canceled this workflow (if applicable)
- `trigger_inputs` (TriggerInputs, optional) — A key-value pair where the key is the `field_name` defined in the `trigger_input_schema` of the workflow definition, and the value is the actual input data. Supported types include string, number, boolean, object, or array.
- `total_steps` (integer, optional) — Total number of steps configured in the workflow
- `last_completed_step` (integer, optional) — The index of the most recently completed step
- `last_completed_step_name` (string, optional, nullable) — The name of the most recently completed step
- `tags` (list of string, optional) — Custom tags for organization or filtering
- `metadata` (WorkflowInstanceMetadata, optional) — Additional metadata related to this workflow instance

## Errors

### 400 Bad Request Error

Bad Request - The request could not be understood or was missing required parameters.

- `type` (string, required) — A URI reference that identifies the problem type. Use 'about:blank' when the problem has no additional semantics beyond the HTTP status code.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `timestamp` (datetime, optional) — The timestamp when the error occurred.
- `request_id` (string, optional) — Correlation identifier for the request, useful for support investigations.
- `errors` (list of ValidationError, optional) — Optional list of individual validation or domain errors.

### 401 Unauthorized Error

Unauthorized - Authentication is required and has failed or not been provided.

- `type` (string, required) — A URI reference that identifies the problem type. Use 'about:blank' when the problem has no additional semantics beyond the HTTP status code.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `timestamp` (datetime, optional) — The timestamp when the error occurred.
- `request_id` (string, optional) — Correlation identifier for the request, useful for support investigations.
- `errors` (list of ValidationError, optional) — Optional list of individual validation or domain errors.

### 403 Forbidden Error

Forbidden - The request was valid, but you do not have permission to perform the action.

- `type` (string, required) — A URI reference that identifies the problem type. Use 'about:blank' when the problem has no additional semantics beyond the HTTP status code.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `timestamp` (datetime, optional) — The timestamp when the error occurred.
- `request_id` (string, optional) — Correlation identifier for the request, useful for support investigations.
- `errors` (list of ValidationError, optional) — Optional list of individual validation or domain errors.

### 404 Not Found Error

Not Found - The requested resource could not be found.

- `type` (string, required) — A URI reference that identifies the problem type. Use 'about:blank' when the problem has no additional semantics beyond the HTTP status code.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `timestamp` (datetime, optional) — The timestamp when the error occurred.
- `request_id` (string, optional) — Correlation identifier for the request, useful for support investigations.
- `errors` (list of ValidationError, optional) — Optional list of individual validation or domain errors.

### 500 Internal Server Error

Internal Server Error

- `type` (string, required) — A URI reference that identifies the problem type. Use 'about:blank' when the problem has no additional semantics beyond the HTTP status code.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `timestamp` (datetime, optional) — The timestamp when the error occurred.
- `request_id` (string, optional) — Correlation identifier for the request, useful for support investigations.
- `errors` (list of ValidationError, optional) — Optional list of individual validation or domain errors.

## Types

### TriggerInputs

A key-value pair where the key is the `field_name` defined in the `trigger_input_schema` of the workflow definition, and the value is the actual input data. Supported types include string, number, boolean, object, or array.

- string
- double
- boolean
- map from string to any
- list of any

### WorkflowInstanceMetadata

Additional metadata related to this workflow instance

- `workflow_created_by` (string, optional) — Identifier of the user who originally created the workflow definition
- `workflow_version` (string, optional) — Version string of the deployed workflow
- `workflow_metadata_id` (string, optional) — Identifier for workflow definition metadata in the system

### ValidationError

A single field-level or domain validation error.

- `code` (string, required) — Machine-readable error code.
- `message` (string, required) — Human-readable description of the error.
- `target` (string, optional) — The field or parameter this error relates to.

## Examples

**Response**

```json
{
  "id": "fa4b77cb-dc69-4960-bd5c-9e6bf3c182e7",
  "name": "latency again",
  "workflow_status": "In Progress",
  "template_id": "25b96463-4aad-4cae-bbf9-15fbd5205b72",
  "account_id": "3b4453f5-869f-4c6a-8f1d-bcc260357144",
  "started_at": "2024-10-24T17:32:20.260Z",
  "started_by": "0ccdbb0b-a72e-452f-95f0-9f19654cb620",
  "started_by_name": "Jane Doe",
  "started_by_role": "Preparer",
  "ended_at": "2024-10-24T19:54:11.345Z",
  "expires_at": "2024-10-25T17:32:20.261Z",
  "last_modified_at": "2024-10-24T17:32:20.610Z",
  "canceled_at": "2024-10-24T19:54:11.345Z",
  "canceled_by": "",
  "total_steps": 3,
  "last_completed_step": 0,
  "last_completed_step_name": null,
  "tags": [],
  "metadata": {
    "workflow_created_by": "f6a8f4d2-b1b5-4fa4-b067-3de168907526",
    "workflow_version": "1.0.0",
    "workflow_metadata_id": "66df63a436871a9d22c63b9f"
  },
  "trigger_input": {}
}
```