> For the complete documentation index, see [llms.txt](https://docs.pyck.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pyck.cloud/graphql-api/queries/assignableworkflowexecutions.md).

# AssignableWorkflowExecutions

Query workflow executions that have pending user tasks

Audience: Programmer

Returns a paginated list of Temporal workflow executions that have pending user tasks. Unlike `workflowExecutions`, this query filters results to only include workflows where the `ActivityCount` in `UserDataInput` is greater than zero. Workflows that do not have user task handlers or have no pending activities are excluded from the results.

This query is designed for client applications that need to present a list of workflows awaiting user action, such as a task inbox or assignment queue, without requiring the client to fetch all executions and filter locally.

The query uses the same pagination interface, filtering options, and return types as `workflowExecutions`.

## Service

Owned by the **Workflow** service.

## Arguments

| Name      | Type                           | Description                                             |
| --------- | ------------------------------ | ------------------------------------------------------- |
| `where`   | `WorkflowExecutionsWhereInput` | Filter criteria for workflow executions                 |
| `first`   | `Int`                          | Maximum number of executions to return. Defaults to 100 |
| `after`   | `String`                       | Pagination cursor from previous response                |
| `orderBy` | `WorkflowExecutionOrder`       | Ordering options for the returned list                  |

## Return Type

`WorkflowExecutionInfoConnection!` - A connection containing workflow execution information with pagination support.

### Connection Fields

| Field        | Type                            | Description                                                          |
| ------------ | ------------------------------- | -------------------------------------------------------------------- |
| `edges`      | `[WorkflowExecutionInfoEdge!]!` | List of workflow execution edges                                     |
| `pageInfo`   | `WorkflowExecutionPageInfo!`    | Pagination information                                               |
| `totalCount` | `Int!`                          | Total count of all assignable executions (not just the current page) |

### Edge Fields

| Field    | Type                     | Description                        |
| -------- | ------------------------ | ---------------------------------- |
| `node`   | `WorkflowExecutionInfo!` | The workflow execution information |
| `cursor` | `String!`                | Cursor for pagination              |

## Filter Options (WorkflowExecutionsWhereInput)

The `where` parameter accepts the same `WorkflowExecutionsWhereInput` as the `workflowExecutions` query, including support for logical operators (`or`, `and`, `not`) and advanced string predicates (`hasPrefix`, `hasSuffix`, `equalFold`, `containsFold`).

For complete documentation of all available filters, see [workflowExecutions](/graphql-api/queries/workflowexecutions.md#filter-options-workflowexecutionswhereinput).

Common filters include:

### Workflow Identification

| Filter                | Type        | Description                            |
| --------------------- | ----------- | -------------------------------------- |
| `workflowID`          | `String`    | Exact workflow ID match                |
| `workflowIDIn`        | `[String!]` | Match any of the provided workflow IDs |
| `workflowIDHasPrefix` | `String`    | Workflow ID starts with                |
| `workflowIDContains`  | `String`    | Workflow ID contains substring         |
| `runID`               | `String`    | Exact run ID match                     |
| `runIDIn`             | `[String!]` | Match any of the provided run IDs      |

### Workflow Type

| Filter              | Type        | Description                          |
| ------------------- | ----------- | ------------------------------------ |
| `typeName`          | `String`    | Exact workflow type name             |
| `typeNameIn`        | `[String!]` | Match any of the provided type names |
| `typeNameContains`  | `String`    | Type name contains substring         |
| `typeNameHasPrefix` | `String`    | Type name starts with                |

### Status

| Filter        | Type        | Description                                           |
| ------------- | ----------- | ----------------------------------------------------- |
| `status`      | `String`    | Exact status match (RUNNING, COMPLETED, FAILED, etc.) |
| `statusIn`    | `[String!]` | Match any of the provided statuses                    |
| `statusNotIn` | `[String!]` | Exclude specific statuses                             |

### Time Filters

| Filter            | Type      | Description                    |
| ----------------- | --------- | ------------------------------ |
| `startTime`       | `String`  | Exact start time (ISO 8601)    |
| `startTimeGT`     | `String`  | Started after                  |
| `startTimeGTE`    | `String`  | Started at or after            |
| `startTimeLT`     | `String`  | Started before                 |
| `startTimeLTE`    | `String`  | Started at or before           |
| `closeTime`       | `String`  | Exact close time               |
| `closeTimeIsNil`  | `Boolean` | Still running (no close time)  |
| `closeTimeNotNil` | `Boolean` | Has completed (has close time) |

### Search Attributes

| Filter       | Type        | Description                   |
| ------------ | ----------- | ----------------------------- |
| `service`    | `String`    | Service name search attribute |
| `serviceIn`  | `[String!]` | Match any of the services     |
| `dataType`   | `String`    | Data type search attribute    |
| `dataTypeIn` | `[String!]` | Match any data types          |
| `dataId`     | `String`    | Data ID search attribute      |
| `dataIdIn`   | `[String!]` | Match any data IDs            |

### Assignment

| Filter           | Type        | Description          |
| ---------------- | ----------- | -------------------- |
| `assignee`       | `String`    | Exact assignee match |
| `assigneeIn`     | `[String!]` | Match any assignees  |
| `assigneeIsNil`  | `Boolean`   | Unassigned workflows |
| `assigneeNotNil` | `Boolean`   | Assigned workflows   |
| `groupBy`        | `String`    | Group by value       |

### Title and Group Title (pyck\_title / pyck\_group\_title search attributes)

| Filter                | Type        | Description                                                   |
| --------------------- | ----------- | ------------------------------------------------------------- |
| `title`               | `String`    | Exact match against `pyck_title` (per-workflow display label) |
| `titleIn`             | `[String!]` | Match any of the provided titles                              |
| `titleHasPrefix`      | `String`    | Title starts with                                             |
| `titleContainsFold`   | `String`    | Case-insensitive substring match                              |
| `titleIsNil`          | `Boolean`   | Title not set (matches missing attribute or empty string)     |
| `groupTitle`          | `String`    | Exact match against `pyck_group_title` (group header label)   |
| `groupTitleIn`        | `[String!]` | Match any of the provided group titles                        |
| `groupTitleHasPrefix` | `String`    | Group title starts with                                       |
| `groupTitleIsNil`     | `Boolean`   | Group title not set                                           |

See the [workflowExecutions filter reference](/graphql-api/queries/workflowexecutions.md#title-pyck_title-search-attribute) for the full list of title and group title predicates (NEQ, NotIn, Contains, HasSuffix, EqualFold, ContainsFold, NotNil).

### Logical Operators

| Filter | Type                              | Description               |
| ------ | --------------------------------- | ------------------------- |
| `and`  | `[WorkflowExecutionsWhereInput!]` | All conditions must match |
| `or`   | `[WorkflowExecutionsWhereInput!]` | Any condition matches     |
| `not`  | `WorkflowExecutionsWhereInput`    | Negate condition          |

## Ordering Options (WorkflowExecutionOrder)

| Field       | Values                                                                      | Description                                 |
| ----------- | --------------------------------------------------------------------------- | ------------------------------------------- |
| `direction` | `ASC`, `DESC`                                                               | Sort direction (defaults to `DESC`)         |
| `field`     | `START_TIME`, `CLOSE_TIME`, `WORKFLOW_ID`, `STATUS`, `TITLE`, `GROUP_TITLE` | Field to sort by (defaults to `START_TIME`) |

`TITLE` orders alphabetically by the `pyck_title` search attribute; `GROUP_TITLE` orders by the `pyck_group_title` search attribute.

## Usage Examples

### List All Assignable Workflows

```graphql
query {
  assignableWorkflowExecutions(
    first: 50
    orderBy: { direction: DESC, field: START_TIME }
  ) {
    edges {
      node {
        execution {
          workflowId
          id
        }
        type {
          name
        }
        status
        startTime
        searchAttributes {
          key
          value
        }
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}
```

### Filter by Workflow Type

Retrieve assignable workflows for a specific workflow type, for example only picking-related workflows awaiting user action.

```graphql
query {
  assignableWorkflowExecutions(
    where: {
      typeName: "PickingWorkflow"
    }
    first: 25
  ) {
    edges {
      node {
        execution {
          workflowId
          id
        }
        type {
          name
        }
        status
        startTime
        searchAttributes {
          key
          value
        }
        taskQueue
      }
    }
    totalCount
  }
}
```

### Filter Unassigned Workflows Awaiting Action

Find workflows that have pending user tasks but are not yet assigned to anyone.

```graphql
query {
  assignableWorkflowExecutions(
    where: {
      assigneeIsNil: true
      status: "RUNNING"
    }
    first: 100
    orderBy: { direction: ASC, field: START_TIME }
  ) {
    edges {
      node {
        execution {
          workflowId
          id
        }
        type {
          name
        }
        status
        startTime
        searchAttributes {
          key
          value
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}
```

### Filter by Service and Data Type

List assignable workflows belonging to a specific service and data type.

```graphql
query {
  assignableWorkflowExecutions(
    where: {
      service: "picking"
      dataType: "picking-order"
    }
    first: 50
  ) {
    edges {
      node {
        execution {
          workflowId
        }
        status
        searchAttributes {
          key
          value
        }
      }
    }
    totalCount
  }
}
```

### Paginating Through Results

```graphql
# First page
query FirstPage {
  assignableWorkflowExecutions(
    where: { status: "RUNNING" }
    first: 25
  ) {
    edges {
      node {
        execution { workflowId }
        type { name }
        status
        searchAttributes { key value }
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Next page (use endCursor from previous response)
query NextPage {
  assignableWorkflowExecutions(
    where: { status: "RUNNING" }
    first: 25
    after: "YXNzaWduYWJsZV9vZmZzZXQ6MjU="
  ) {
    edges {
      node {
        execution { workflowId }
        type { name }
        status
        searchAttributes { key value }
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Example Response

```json
{
  "data": {
    "assignableWorkflowExecutions": {
      "edges": [
        {
          "node": {
            "execution": {
              "workflowId": "picking-order-12345",
              "id": "run-abc-123"
            },
            "type": {
              "name": "PickingWorkflow"
            },
            "status": "RUNNING",
            "startTime": "2024-01-15T10:30:00Z",
            "closeTime": null,
            "searchAttributes": [
              { "key": "pyck_title", "value": "Picking Order #12345" },
              { "key": "pyck_group_title", "value": "Zone A" }
            ]
          },
          "cursor": "YXNzaWduYWJsZV9vZmZzZXQ6MQ=="
        },
        {
          "node": {
            "execution": {
              "workflowId": "receiving-inbound-67890",
              "id": "run-def-456"
            },
            "type": {
              "name": "ReceivingWorkflow"
            },
            "status": "RUNNING",
            "startTime": "2024-01-15T09:15:00Z",
            "closeTime": null,
            "searchAttributes": [
              { "key": "pyck_title", "value": "Receiving Inbound #67890" },
              { "key": "pyck_group_title", "value": "Dock B" }
            ]
          },
          "cursor": "YXNzaWduYWJsZV9vZmZzZXQ6Mg=="
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "YXNzaWduYWJsZV9vZmZzZXQ6Mg=="
      },
      "totalCount": 47
    }
  }
}
```

## Comparison with workflowExecutions

| Feature                           | `workflowExecutions`                 | `assignableWorkflowExecutions`       |
| --------------------------------- | ------------------------------------ | ------------------------------------ |
| Returns all executions            | Yes                                  | No                                   |
| Filters by user task availability | No                                   | Yes (ActivityCount > 0)              |
| Arguments                         | `where`, `first`, `after`, `orderBy` | `where`, `first`, `after`, `orderBy` |
| Return type                       | `WorkflowExecutionInfoConnection!`   | `WorkflowExecutionInfoConnection!`   |
| Pagination support                | Yes                                  | Yes                                  |

## Performance Considerations

* This query fetches all pages from Temporal upfront to compute an accurate `totalCount`, then paginates the results in-memory using offset-based cursors.
* For single-tenant requests, all matching workflows are retrieved from Temporal first, filtered for assignability, and then paginated.
* For multi-tenant requests, all matching executions are fetched first, then filtered concurrently across tenants.
* Because all results must be fetched to determine the total count, this query may have higher latency for large result sets compared to simple cursor-based pagination.
* Use filtering parameters such as `typeName`, `status`, or `service` to narrow results and improve performance.
* The default page size is 100 if `first` is not specified.

## Important Changes

{% hint style="info" %}
**Pagination Fix (March 2026)**: The pagination implementation was updated to fix two critical bugs:

1. `totalCount` now returns the total number of assignable workflows across all pages (previously returned only the current page count)
2. Cursor format changed from `workflowId:runId` to opaque offset-based cursors for consistent pagination

If you have existing client code that parses cursor values, you must update it to treat cursors as opaque strings.
{% endhint %}

## Notes

* Only workflows with `ActivityCount > 0` in their `UserDataInput` are returned. This means the workflow must have registered user task handlers and have at least one pending activity.
* Workflows without user task handlers or where all activities have been completed will not appear in the results.
* The query shares the same return type (`WorkflowExecutionInfoConnection`) as `workflowExecutions`, so client code can be reused across both queries.
* Cursor values are opaque offset-based strings (base64-encoded). Do not attempt to parse or construct cursors manually; always use the `endCursor` value from the `pageInfo` response.
* **Logical operators** (`or`, `and`, `not`) are fully supported for building complex filter conditions.
* **String predicates** include both case-sensitive and case-insensitive variants for flexible searching.

## Related Documentation

* [workflowExecutions](/graphql-api/queries/workflowexecutions.md) - Query all workflow executions
* [workflowHistory](/graphql-api/queries/workflowhistory.md) - Fetch workflow history events
* [workflowAssignee](/graphql-api/queries/workflowassignee.md) - Retrieve workflow assignee
* [WorkflowExecutionInfo](/graphql-api/types/workflowexecutioninfo.md) - Execution info type
* [WorkflowExecutionInfoConnection](/graphql-api/types/workflowexecutioninfoconnection.md) - Connection type


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pyck.cloud/graphql-api/queries/assignableworkflowexecutions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.