> 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

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

Returns a paginated list of workflow instances across all workflow definitions for the specified account.

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

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

### Query parameters

- `started_by_id` (string, optional) — Filter instances by the user who started them. Non-admin users without MANAGE permission will always be restricted to their own userId, and any attempt to filter by another userId will result in a 403 Forbidden response.
- `workflow_definition_id` (list of string, optional) — Filter instances by one or more workflow definition IDs. Repeat the parameter for multiple values.
- `status` (enum, optional) — Filter instances by status.
  - Allowed values: `Created`, `In Progress`, `Completed`, `Failed`, `Canceled`, `Completed With Errors`, `Expired`
- `ctoken` (string, optional) — Opaque token returned from a previous response to retrieve the next page of results. Omit to retrieve the first page.
- `page_size` (integer, optional, default: 10) — Number of items per page.

## Response

### 200

A paginated list of workflow instances for the specified account.

- `instances` (list of AccountWorkflowInstance, required)
- `total_set_size` (integer, required) — Approximate total number of matching workflow instances across all pages. This value is evaluated once at the start of the query and cached for subsequent pages, so it may not reflect additions or deletions that occur after the initial request.
- `result_set_size` (integer, required) — Number of items returned in the current page.
- `ctoken` (string, required, nullable) — Opaque token to retrieve the next page of results. Null when there are no more pages. Pass this value as the ctoken query parameter in the next request.

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

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

### AccountWorkflowInstance

A workflow instance returned in snake_case format. Key fields are documented below; additional properties may be present.

- `workflow_instance_id` (string, optional) — Unique identifier for the workflow instance.
- `workflow_definition_id` (string, optional) — The workflow definition this instance was created from.
- `account_id` (string, optional) — The account that owns this instance.
- `trigger_type` (enum, optional) — How the workflow instance was triggered.
  - Allowed values: `Http`, `Http-API`, `Url`, `Manual`, `CLM-Workflow`, `API`, `Event`, `Agreement-Desk`
- `progress` (AccountWorkflowInstanceProgress, optional) — Progress information for the workflow instance.
- `version_details` (AccountWorkflowInstanceVersionDetails, optional) — Deployment version details.
- `instance_state` (enum, optional) — Current state of the workflow instance.
  - Allowed values: `Created`, `In Progress`, `Failed`, `Completed`, `Canceled`, `Completed With Errors`, `Expired`
- `last_activity_date` (datetime, optional) — Timestamp of the last activity on this instance.
- `expire_date` (datetime, optional) — Expiration date of the workflow instance.
- `start_date` (datetime, optional) — When the workflow instance was started.
- `creator_id` (string, optional) — The user who created this instance.
- `started_by` (AccountWorkflowInstanceStartedBy, optional) — Information about who started the instance.
- `instance_name` (string, optional) — Display name of the workflow instance.
- `end_date` (datetime, optional, nullable) — Date and time when the workflow instance completed or ended.
- `cancel_date` (datetime, optional, nullable) — When the instance was canceled (if applicable).
- `tags` (list of string, optional, nullable) — Custom tags associated with the workflow instance.
- `last_updated_by` (AccountWorkflowInstanceLastUpdatedBy, optional) — Information about the last user to update this instance.

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

### AccountWorkflowInstanceProgress

Progress information for the workflow instance.

- `total_steps` (integer, optional)
- `completed_steps` (integer, optional)
- `current_completed_step_name` (string, optional)

### AccountWorkflowInstanceVersionDetails

Deployment version details.

- `deploy_version` (string, optional)
- `deploy_workflow_definition_metadata_id` (string, optional)

### AccountWorkflowInstanceStartedBy

Information about who started the instance.

- `started_by_name` (string, optional)
- `started_by_id` (string, optional)
- `started_by_type` (enum, optional)
  - Allowed values: `Anonymous`, `Preparer`, `Participant`, `OnBehalfOf`, `System`, `SubWorkflow`

### AccountWorkflowInstanceLastUpdatedBy

Information about the last user to update this instance.

- `user_name` (string, optional)
- `user_id` (string, optional)
- `date` (datetime, optional)
- `operation` (enum, optional)
  - Allowed values: `Cancel`

## Examples

**Response**

```json
{
  "instances": [
    {
      "workflow_instance_id": "0ca3ef23-eb34-45d7-98cf-fb31a8b147a7",
      "workflow_definition_id": "c6f818da-4b15-4ac7-81b6-e70ea5e2f097",
      "account_id": "84f8efc2-cb73-4215-b218-f2abfda4a27b",
      "trigger_type": "Url",
      "progress": {
        "total_steps": 3,
        "completed_steps": 3,
        "current_completed_step_name": "Show a Confirmation Screen"
      },
      "version_details": {
        "deploy_version": "3.0.0",
        "deploy_workflow_definition_metadata_id": "6861b5003a05d457ba7f7dee"
      },
      "instance_state": "Completed",
      "last_activity_date": "2026-03-19T20:45:12.285Z",
      "expire_date": "2026-06-16T20:40:54.008Z",
      "start_date": "2026-03-18T20:40:44.933Z",
      "creator_id": "7d445df2-4110-4470-a8df-1553fe530c72",
      "started_by": {
        "started_by_name": "Maestro Backend",
        "started_by_id": "7d445df2-4110-4470-a8df-1553fe530c72",
        "started_by_type": "OnBehalfOf"
      },
      "instance_name": "2026-03-18T20:40:43.817Z_0ca3ef23-eb34-45d7-98cf-fb31a8b147a7",
      "end_date": "2026-03-19T20:45:12.285Z",
      "tags": null
    },
    {
      "workflow_instance_id": "af2637b0-d5f2-4644-8dbd-1d9f7b42b77c",
      "workflow_definition_id": "c6f818da-4b15-4ac7-81b6-e70ea5e2f097",
      "account_id": "84f8efc2-cb73-4215-b218-f2abfda4a27b",
      "trigger_type": "Url",
      "progress": {
        "total_steps": 3,
        "completed_steps": 3,
        "current_completed_step_name": "Show a Confirmation Screen"
      },
      "version_details": {
        "deploy_version": "3.0.0",
        "deploy_workflow_definition_metadata_id": "6861b5003a05d457ba7f7dee"
      },
      "instance_state": "Completed",
      "last_activity_date": "2026-03-19T20:39:21.126Z",
      "expire_date": "2026-06-16T20:35:50.387Z",
      "start_date": "2026-03-18T20:35:31.707Z",
      "creator_id": "7d445df2-4110-4470-a8df-1553fe530c72",
      "started_by": {
        "started_by_name": "Maestro Backend",
        "started_by_id": "7d445df2-4110-4470-a8df-1553fe530c72",
        "started_by_type": "OnBehalfOf"
      },
      "instance_name": "2026-03-18T20:35:30.483Z_af2637b0-d5f2-4644-8dbd-1d9f7b42b77c",
      "end_date": "2026-03-19T20:39:21.126Z",
      "tags": null
    }
  ],
  "total_set_size": 2,
  "result_set_size": 2,
  "ctoken": null
}
```