> 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 ProcedureMethodExecutionInstance items

GET https://{tenant_name}.benchling.com/api/v3/procedure-method-execution-instance/items

List ProcedureMethodExecutionInstance items.

Reference: https://docs.benchling.com/docs/api/benchling-api/procedure-method-execution-instance/list

## Authentication

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

## Request

### Query parameters

- `archiveReason.anyOf` (string, optional) — Restricts items to those with any of the specified archive reasons. Use "NOT_ARCHIVED" to filter for unarchived items. Use "ANY_ARCHIVED" to filter for archived items regardless of reason. Use "ANY_ARCHIVED_OR_NOT_ARCHIVED" to return items for both archived and unarchived. Comma-separated list.
- `archived.anyOf` (boolean, optional) — If true, returns archived items. If false, returns unarchived items. If both true and false, returns archived and unarchived items. Comma-separated list.
- `createdAt.gt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created after the specified time. e.g. > 2017-04-30.
- `createdAt.gte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or after the specified time. e.g. >= 2017-04-30.
- `createdAt.lt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created before the specified time. e.g. \< 2017-04-30.
- `createdAt.lte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or before the specified time. e.g. \<= 2017-04-30.
- `id.anyOf` (string, optional) — Restricts results to those matching any of the specified IDs. Comma-separated list.
- `modifiedAt.gt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified after the specified time. e.g. > 2017-04-30.
- `modifiedAt.gte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or after the specified time. e.g. >= 2017-04-30.
- `modifiedAt.lt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified before the specified time. e.g. \< 2017-04-30.
- `modifiedAt.lte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or before the specified time. e.g. \<= 2017-04-30.
- `nextToken` (string, optional) — Token for pagination
- `omit` (string, optional) — Comma-separated list of top-level fields to omit from each returned item. Cannot overlap with returning.
- `pageSize` (integer, optional) — Number of results to return. Defaults to 50, maximum of 100.
- `procedureRun.eq` (string, optional) — ID of a procedure run. Restricts results to only those that are part of the specified procedure run.
- `procedureRunConditionReplicate.anyOf` (string, optional) — Restricts results to only those that are part of procedure run condition-replicates matching any of the specified procedure run condition-replicate IDs. Comma-separated list.
- `returning` (string, optional) — Comma-separated list of top-level fields to include in each returned item. Cannot overlap with omit.
- `templateProcedureMethodVersion.eq` (string, optional) — ID of a procedure method definition version. Restricts results to only those that have the specified template procedure method version.
- `worksheet.anyOf` (string, optional) — Restricts results to only those executed in worksheets matching any of the specified worksheet IDs. Comma-separated list.
- `sort` (enum, optional, default: modifiedAt:desc) — Method by which to order results. Valid sorts are: createdAt (created time, oldest first) and modifiedAt (modified time, oldest first). Use :asc or :desc to specify ascending or descending order. Default is modifiedAt:desc.
  - Allowed values: `createdAt:asc`, `createdAt:desc`, `modifiedAt:asc`, `modifiedAt:desc`

### Headers

- `EARLY-ACCESS` (string, optional) — Set to true to access beta operations via /api/v3.

## Response

### 200

OK

- `items` (list of ProcedureMethodExecutionInstance, optional)
- `nextToken` (string, optional)

## Errors

### 400 Procedure Method Execution Instance List Request Bad Request Error

Bad Request

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 403 Procedure Method Execution Instance List Request Forbidden Error

Forbidden

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 404 Procedure Method Execution Instance List Request Not Found Error

Not Found

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 429 Procedure Method Execution Instance List Request Too Many Requests Error

Too Many Requests

- `detail` (TooManyRequestsErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)
- `violated-policies` (list of enum, optional) — The budget policies that rejected the request, in canonical order: `user`, `integration`, then `tenant`.
  - Allowed values: `user`, `integration`, `tenant`

### 500 Procedure Method Execution Instance List Request Internal Server Error

Internal Server Error

- `detail` (InternalServerErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `errorId` (string, optional)

## Types

### ProcedureMethodExecutionInstance

An instance of a method being executed within a procedure run. When a scientist runs a procedure, each method in the flowchart becomes a ProcedureMethodExecutionInstance that tracks the actual execution: the worksheet where data is entered (`worksheet`), the associated task (`methodTask`), step groups with execution instances (`stepGroups`), and all parameter values (planned, confirmed, and measured). Links to its `ProcedureRun`, the template method it's based on (`templateMethodVersion`), and the specific condition/replicate it belongs to (`procedureRunConditionReplicate`). Material flow between methods is tracked via `sourceProcedureMethodExecutionInstanceAssociations` and `targetProcedureMethodExecutionInstanceAssociations`. ## Product mapping - In the Benchling UI, this maps to a **condition-replicate-specific execution of a unit operation** within an active experiment. - Think of this as the runtime counterpart to `ProcedureMethodDefinitionVersion`: - `ProcedureMethodDefinitionVersion` = template/config definition - `ProcedureMethodExecutionInstance` = run-time execution record

- `__typename` (string, optional)
- `archiveReason` (string, optional, nullable)
- `archived` (boolean, optional)
- `createdAt` (string, optional)
- `dataParameterActualValues` (string, optional)
- `dataParameterConfirmationValues` (string, optional)
- `dataParameterPlannedValues` (string, optional) — Source of truth for this specific PMEI's planned data parameter values, with any condition overrides.
- `equipmentConfirmationValues` (string, optional)
- `equipmentPlannedValues` (string, optional) — Source of truth for this specific PMEI's planned equipment values, with any condition overrides.
- `id` (string, optional)
- `materialInputConfirmationValues` (string, optional)
- `materialInputPlannedValues` (string, optional) — Source of truth for this specific PMEI's planned material input values, with any condition overrides. Note: This will not include any process intermediate values when previous methods have not yet been completed.
- `materialOutputConfirmationValues` (string, optional)
- `modifiedAt` (string, optional)
- `procedureRun` (ProcedureRunRef, optional)
- `procedureRunConditionReplicate` (ProcedureRunConditionReplicateRef, optional)
- `stepGroups` (list of ProcedureExecutionStepGroup, optional)
- `taskTransitionExtensions` (list of TaskTransitionExtension, optional)
- `templateMethodVersion` (ProcedureMethodDefinitionVersionRef, optional) — The "template" method version represents the PMDV on the procedure template that this PMEI is based on. In most cases this is equivalent to the planMethodVersion. They only differ on older legacy ProcedureRuns, where "plan" PMDVs belong to a legacy "plan" ProcedureFlowchart model and we compiled a dedicated ProcedureFlowchart for this run (with its own PMDVs) based on the template's legacy ProcedureFlowchart. Do not directly use the parameter planned values from this PMDV. dataParameterPlannedValues, materialInputPlannedValues, and equipmentPlannedValues on the PMEI itself are the source of truth instead, since they account for experiment planning condition overrides that are not reflected on the PMDV. Do not use the confirmation methods from the parameter versions in this PMDV. parameterConfirmationMethods on the PMEI itself is the source of truth instead, since it accounts for experiment planning condition overrides that are not reflected on the PMDV.

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### ProcedureRunRef

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

### ProcedureRunConditionReplicateRef

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

### ProcedureExecutionStepGroup

Groups step execution instances by their execution phase during a procedure run. Analogous to `ProcedureStepGroup` but contains actual execution instances (`ProcedureStepExecutionInstance`) rather than step definitions. Each group's steps are ordered by execution sequence.

- `__typename` (string, optional)
- `group` (enum, optional)
  - Allowed values: `PRE_RUN`, `RUN`, `POST_RUN`
- `steps` (list of ProcedureStepExecutionInstanceRef, optional)

### TaskTransitionExtension

Records a status change event on a method task during procedure execution. Captures the comment provided, the human-readable status name, and the timestamp when the transition occurred. Used to track the history of task state changes.

- `__typename` (string, optional)
- `comment` (string, optional)
- `statusDisplayName` (string, optional)
- `timestampUtcIsoformat` (string, optional)

### ProcedureMethodDefinitionVersionRef

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

### ProcedureStepExecutionInstanceRef

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

## Examples

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "archiveReason": "archiveReason",
      "archived": true,
      "createdAt": "createdAt",
      "dataParameterActualValues": "dataParameterActualValues",
      "dataParameterConfirmationValues": "dataParameterConfirmationValues",
      "dataParameterPlannedValues": "dataParameterPlannedValues",
      "equipmentConfirmationValues": "equipmentConfirmationValues",
      "equipmentPlannedValues": "equipmentPlannedValues",
      "id": "id",
      "materialInputConfirmationValues": "materialInputConfirmationValues",
      "materialInputPlannedValues": "materialInputPlannedValues",
      "materialOutputConfirmationValues": "materialOutputConfirmationValues",
      "modifiedAt": "modifiedAt",
      "stepGroups": [
        {}
      ],
      "taskTransitionExtensions": [
        {}
      ]
    }
  ],
  "nextToken": "nextToken"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/procedure-method-execution-instance/items"

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

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

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/procedure-method-execution-instance/items';
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);
}
```