> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

# List workflow task groups

GET https://{tenant_name}.benchling.com/api/v2/workflow-task-groups

List workflow task groups

Reference: https://docs.benchling.com/docs/api/v2/benchling-api/workflow-task-groups/list-workflow-task-groups

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Query parameters

- `ids` (string, optional) — Comma separated list of workflow task group IDs
- `schemaId` (string, optional) — The workflow task schema ID of tasks in this task group
- `folderId` (string, optional) — A folder ID
- `projectId` (string, optional) — A project ID
- `mentionedIn` (string, optional) — A comma separated list entry IDs
- `watcherIds` (string, optional) — Comma separated list of user IDs or "null"
- `executionTypes` (string, optional) — Comma separated list of workflow execution types. Acceptable execution types are "DIRECT" and "ENTRY"
- `responsibleTeamIds` (string, optional) — Comma separated list of team IDs or "null"
- `statusIds.anyOf` (string, optional) — Commas separated list of Status ids. Maximum of 100. Returns workflows where at least one task is of one of the provided statuses.
- `statusIds.noneOf` (string, optional) — Commas separated list of Status ids. Returns workflows where none of the tasks are of any of the provided statuses.
- `statusIds.only` (string, optional) — Commas separated list of Status ids. Returns workflows where all of the tasks are of one of the provided statuses.
- `name` (string, optional) — The name of the workflow task group
- `nameIncludes` (string, optional) — Part of the name of the workflow task group
- `creatorIds` (string, optional) — Comma separated list of user IDs.
- `modifiedAt` (string, optional) — Datetime, in RFC 3339 format. Supports the > and \< operators. Time zone defaults to UTC. Restricts results to those modified in the specified range. e.g. > 2017-04-30. Date ranges can be specified with the following nomenclature > YYYY-MM-DD AND \<YYYY-MM-DD.
- `nextToken` (string, optional)
- `pageSize` (integer, optional, default: 50)
- `displayIds` (string, optional) — Comma-separated list of Workflow Display IDs.
- `archiveReason` (string, optional) — Archive reason. Restricts items to those with the specified archive reason. Use "NOT_ARCHIVED" to filter for unarchived workflow task groups. Use "ANY_ARCHIVED" to filter for archived workflow task groups regardless of reason. Use "ANY_ARCHIVED_OR_NOT_ARCHIVED" to return items for both archived and unarchived.

## Response

### 200

OK

- `nextToken` (string, optional)
- `workflowTaskGroups` (list of WorkflowTaskGroup, optional)

## Errors

### 400 Bad Request Error

Bad request

- `error` (BadRequestErrorError, optional)

## Types

### WorkflowTaskGroup

- `displayId` (string, optional) — User-friendly ID of the workflow task group
- `id` (string, optional) — The ID of the workflow task group
- `name` (string, optional) — The name of the workflow task group
- `archiveRecord` (ArchiveRecord, optional, nullable)
- `createdAt` (string, optional) — The ISO formatted date and time that the task group was created
- `creationOrigin` (CreationOrigin, optional)
- `creator` (UserSummary, optional)
- `folder` (Folder, optional)
- `modifiedAt` (string, optional) — The ISO formatted date and time that the task group was last modified
- `outputs` (list of WorkflowOutputSummary, optional) — The outputs of the workflow task group
- `responsibleTeam` (TeamSummary, optional, nullable)
- `watchers` (list of UserSummary, optional) — The users watching the workflow task group
- `webURL` (string, optional) — URL of the workflow task group
- `workflowTaskSchema` (WorkflowTaskSchemaSummary, optional)
- `workflowTasks` (list of WorkflowTaskSummary, optional) — The input tasks to the workflow task group
- `executionType` (enum, optional) — The method by which the workflow is executed
  - Allowed values: `DIRECT`, `ENTRY`, `FLOWCHART`, `PROCEDURE`, `PROCEDURE_METHOD`, `PROCEDURE_STEP`
- `flowchartConfigVersionId` (string, optional) — The flowchart configuration that this task group uses. This will be null if the task group does not have executionType FLOWCHART.
- `flowchartTaskGroups` (list of WorkflowNodeTaskGroupSummary, optional) — The task groups that are members of the flowchart that this task group is the root of. This will be null this task group is not the root task group of a flowchart (eg if the task group does not have executionType FLOWCHART).
- `nodeConfig` (WorkflowFlowchartNodeConfig, optional) — The node in a Flowchart that this task group is associated with. This will be null if the task group is not part of a flowchart.
- `rootTaskGroup` (WorkflowTaskGroupSummary, optional) — The task group associated with the root node of the flowchart that this task group is a part of. This will be null if the task group is not part of a flowchart.
- `workflowOutputs` (list of WorkflowOutputSummary, optional) — The outputs of the workflow task group

### BadRequestErrorError

- `message` (string, optional)
- `type` (enum, optional)
  - Allowed values: `invalid_request_error`
- `userMessage` (string, optional)

### ArchiveRecord

- `reason` (string, optional)

### CreationOrigin

- `application` (string, optional, nullable)
- `originId` (string, optional, nullable)
- `originModalUuid` (string, optional, nullable)
- `originType` (string, optional, nullable)

### UserSummary

- `handle` (string, optional)
- `id` (string, optional)
- `name` (string, optional)

### Folder

- `archiveRecord` (ArchiveRecord, optional, nullable)
- `id` (string, optional)
- `name` (string, optional)
- `parentFolderId` (string, optional, nullable) — ID of the parent folder, if it exists
- `projectId` (string, optional) — ID of the containing project

### WorkflowOutputSummary

- `displayId` (string, optional) — User-friendly ID of the workflow task group
- `id` (string, optional) — The ID of the workflow output

### TeamSummary

- `id` (string, optional)
- `name` (string, optional)

### WorkflowTaskSchemaSummary

- `id` (string, optional) — The ID of the workflow task schema
- `name` (string, optional) — The name of the workflow task schema

### WorkflowTaskSummary

- `displayId` (string, optional) — User-friendly ID of the workflow task
- `id` (string, optional) — The ID of the workflow task

### WorkflowNodeTaskGroupSummary

- `displayId` (string, optional) — User-friendly ID of the workflow task group
- `id` (string, optional) — The ID of the workflow task group
- `name` (string, optional) — The name of the workflow task group
- `nodeConfigId` (string, optional) — The node in a Flowchart that this task group is associated with. This will be null if the task group is not part of a flowchart.

### WorkflowFlowchartNodeConfig

- `id` (string, optional) — The ID of the workflow flowchart node config
- `nodeDetails` (WorkflowFlowchartNodeConfigNodeDetails, optional)
- `nodeType` (enum, optional) — The type associated with the node config
  - Allowed values: `ROOT`, `OUTPUT`, `TASK`, `ROUTER`, `END`

### WorkflowTaskGroupSummary

- `displayId` (string, optional) — User-friendly ID of the workflow task group
- `id` (string, optional) — The ID of the workflow task group
- `name` (string, optional) — The name of the workflow task group

### WorkflowFlowchartNodeConfigNodeDetails

- `nodeType`: `END` (END)
  - `id` (string, optional) — The ID of the workflow flowchart end node config details
  - `name` (string, optional) — The name of the end node
- `nodeType`: `OUTPUT` (OUTPUT)
  - `id` (string, optional) — The ID of the workflow output node config details
  - `outputSchema` (SchemaSummary, optional)
- `nodeType`: `ROOT` (ROOT)
  - `id` (string, optional) — The ID of the workflow root node config details
  - `rootTaskSchema` (WorkflowTaskSchemaSummary, optional)
- `nodeType`: `ROUTER` (ROUTER)
  - `id` (string, optional) — The ID of the workflow router node config details
  - `name` (string, optional) — The name of the router node
  - `routerFunctions` (list of WorkflowRouterFunction, optional) — Router functions associated with this router node
- `nodeType`: `TASK` (TASK)
  - `id` (string, optional) — The ID of the workflow task node config details
  - `taskSchema` (WorkflowTaskSchemaSummary, optional)

### SchemaSummary

- `id` (string, optional)
- `name` (string, optional)

### WorkflowRouterFunction

- `edgeConfigId` (string, optional) — The ID of the workflow flowchart edge config associated with this function
- `id` (string, optional) — The function associated with a router node
- `isDefault` (any, optional)
- `name` (string, optional) — The name of a function associated with a router node

## Examples

**Response**

```json
{
  "nextToken": "Im5ldyB0ZXN0Ig==",
  "workflowTaskGroups": [
    {
      "displayId": "string",
      "id": "prs_giVNQcTL",
      "name": "string",
      "archiveRecord": {
        "reason": "Made in error"
      },
      "createdAt": "2020-08-01T00:00:00.000Z",
      "creationOrigin": {
        "application": "string",
        "originId": "string",
        "originModalUuid": "string",
        "originType": "string"
      },
      "creator": {
        "handle": "string",
        "id": "string",
        "name": "string"
      },
      "folder": {
        "archiveRecord": {
          "reason": "Made in error"
        },
        "id": "string",
        "name": "string",
        "parentFolderId": "string",
        "projectId": "string"
      },
      "modifiedAt": "2020-08-01T00:00:00.000Z",
      "outputs": [
        {
          "displayId": "string",
          "id": "wfout_5cJLQKVF"
        }
      ],
      "responsibleTeam": {
        "id": "string",
        "name": "string"
      },
      "watchers": [
        {
          "handle": "string",
          "id": "string",
          "name": "string"
        }
      ],
      "webURL": "string",
      "workflowTaskSchema": {
        "id": "string",
        "name": "string"
      },
      "workflowTasks": [
        {
          "displayId": "string",
          "id": "wftask_OnnsW08k"
        }
      ],
      "executionType": "DIRECT",
      "flowchartConfigVersionId": "wffccv_giVNQcAF",
      "flowchartTaskGroups": [
        {
          "displayId": "string",
          "id": "prs_giVNQcTL",
          "name": "string",
          "nodeConfigId": "wffcnc_giVNQcTL"
        }
      ],
      "nodeConfig": {
        "id": "string",
        "nodeDetails": {
          "nodeType": "ROOT",
          "id": "wfrnd_hbVNQcEM",
          "rootTaskSchema": {
            "id": "string",
            "name": "string"
          }
        },
        "nodeType": "ROOT"
      },
      "rootTaskGroup": {
        "displayId": "string",
        "id": "prs_giVNQcTL",
        "name": "string"
      },
      "workflowOutputs": [
        {
          "displayId": "string",
          "id": "wfout_5cJLQKVF"
        }
      ]
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2/workflow-task-groups"

querystring = {"archiveReason":"NOT_ARCHIVED","modifiedAt":"> 2022-03-01 AND < 2022-04-01","nextToken":"Im5ldyB0ZXN0Ig=="}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v2/workflow-task-groups?archiveReason=NOT_ARCHIVED&modifiedAt=%3E+2022-03-01+AND+%3C+2022-04-01&nextToken=Im5ldyB0ZXN0Ig%3D%3D';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```