> 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 instances list

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

This operation retrieves a list of all available Workflow Builder workflow instances. It returns basic information
about each workflow instance, including its unique identifier (`id`), name, status, timestamps, and
additional metadata.

The response provides key details that help users understand what workflow instances are in progress
or completed, and the relevant data for each. Each workflow instance entry also includes metadata, such
as who started it, when it was last modified, and how many steps have been completed.

### Use Cases:
- Listing all available workflow instances for manual or automated review
- Monitoring which workflow instances are currently running or have finished
- Gathering basic metadata about workflow instances for auditing, logging, or reporting purposes

### Key Features:
- **Comprehensive Instance Overview**: Provides a full list of workflow instances, giving visibility
  into all ongoing and completed workflows within the Workflow Builder platform
- **Metadata for Tracking**: Includes helpful metadata like creation time, last modification date,
  and user details to support audit trails
- **Scalable and Future-Proof**: Designed to handle growing numbers of workflow instances as the
  platform scales


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

## 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.

## Response

### 200

Successful response containing a list of workflow instances

- `data` (list of WorkflowInstance, optional) — Array of workflow instances
- `response_metadata` (ResponseMetadata, optional) — Additional server-side metadata for a given response

## Types

### WorkflowInstance

- `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

### ResponseMetadata

Additional server-side metadata for a given response

- `response_timestamp` (datetime, optional) — The timestamp indicating when the response was generated.
- `response_duration_ms` (integer, optional) — The duration of time, in milliseconds, that the server took to process and respond to the request. This is measured from the time the server received the request until the time the response was sent.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracking and debugging.

### 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

## Examples

**Response**

```json
{
  "data": [
    {
      "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": {}
    }
  ],
  "response_metadata": {
    "response_timestamp": "2024-10-17T14:30:00Z",
    "response_duration_ms": 100,
    "request_id": "3f7c9e4b-851c-4f9b-89e7-123456789abc"
  }
}
```