> 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/mutations/setworkflowtargets.md).

# Set Workflow Targets

Replace the target surfaces of a running workflow execution

Audience: Programmer

Replaces the target surfaces of a running workflow execution. The mutation updates the `pyck_workflow_targets` KeywordList search attribute in Temporal so the workflow becomes visible to (or hidden from) `targets`-based filters in workflow execution queries.

Passing an empty list clears the search attribute, so the workflow no longer matches any targets-based filter.

## Requirements

The workflow's state must implement the `WorkflowTargetsSetter` SDK interface. Workflows that do not implement this interface cannot have their targets updated and will return an error.

## Arguments

| Name    | Type                       | Description                                   |
| ------- | -------------------------- | --------------------------------------------- |
| `input` | `SetWorkflowTargetsInput!` | Input data for replacing the workflow targets |

### SetWorkflowTargetsInput Fields

| Field                 | Type                 | Description                                                                   |
| --------------------- | -------------------- | ----------------------------------------------------------------------------- |
| `workflowId`          | `String!`            | The unique identifier of the workflow                                         |
| `workflowExecutionId` | `String!`            | The specific run ID of the workflow execution                                 |
| `targets`             | `[WorkflowTarget!]!` | The complete list of targets to set. Pass an empty list to clear all targets. |

## Return Type

`SetWorkflowTargetsResponse` - Contains the updated targets after the operation completes. The mutation return type is nullable.

### SetWorkflowTargetsResponse Fields

| Field     | Type                 | Description                                  |
| --------- | -------------------- | -------------------------------------------- |
| `targets` | `[WorkflowTarget!]!` | The list of target surfaces after the update |

## Usage Examples

### Replacing Targets

```graphql
mutation SetTargets {
  setWorkflowTargets(input: {
    workflowId: "picking-order-12345"
    workflowExecutionId: "run-abc-123"
    targets: [WEB, MOBILE]
  }) {
    targets
  }
}
```

### Clearing All Targets

```graphql
mutation ClearTargets {
  setWorkflowTargets(input: {
    workflowId: "picking-order-12345"
    workflowExecutionId: "run-abc-123"
    targets: []
  }) {
    targets
  }
}
```

### Restricting to Mobile Only

```graphql
mutation MobileOnly {
  setWorkflowTargets(input: {
    workflowId: "receiving-inbound-987"
    workflowExecutionId: "run-xyz-789"
    targets: [MOBILE]
  }) {
    targets
  }
}
```

## JavaScript Example

```javascript
const SET_WORKFLOW_TARGETS = gql`
  mutation SetWorkflowTargets($input: SetWorkflowTargetsInput!) {
    setWorkflowTargets(input: $input) {
      targets
    }
  }
`;

// Replace targets
const { data } = await client.mutate({
  mutation: SET_WORKFLOW_TARGETS,
  variables: {
    input: {
      workflowId: "picking-order-12345",
      workflowExecutionId: "run-abc-123",
      targets: ["WEB", "MOBILE"]
    }
  }
});

console.log(`Updated targets: ${data.setWorkflowTargets.targets.join(", ")}`);

// Clear all targets
const { data: cleared } = await client.mutate({
  mutation: SET_WORKFLOW_TARGETS,
  variables: {
    input: {
      workflowId: "picking-order-12345",
      workflowExecutionId: "run-abc-123",
      targets: []
    }
  }
});

console.log(`Targets after clearing: ${cleared.setWorkflowTargets.targets.length}`);
// Output: Targets after clearing: 0
```

## Response Example

### Successful Update

```json
{
  "data": {
    "setWorkflowTargets": {
      "targets": ["WEB", "MOBILE"]
    }
  }
}
```

### Cleared Targets

```json
{
  "data": {
    "setWorkflowTargets": {
      "targets": []
    }
  }
}
```

## Error Handling

The mutation may return errors in the following cases:

### Workflow Does Not Implement WorkflowTargetsSetter

```json
{
  "errors": [{
    "message": "workflow state does not implement WorkflowTargetsSetter",
    "path": ["setWorkflowTargets"]
  }]
}
```

### Invalid WorkflowId or WorkflowExecutionId

```json
{
  "errors": [{
    "message": "invalid WorkflowID",
    "path": ["setWorkflowTargets"]
  }]
}
```

### Invalid Target Value

```json
{
  "errors": [{
    "message": "Value \"INVALID\" does not exist in \"WorkflowTarget\" enum.",
    "path": ["setWorkflowTargets"]
  }]
}
```

### Workflow Not Found or Not Running

```json
{
  "errors": [{
    "message": "workflow not found: picking-order-12345",
    "path": ["setWorkflowTargets"]
  }]
}
```

## Important Notes

* The mutation **replaces** the existing targets — it does not append or merge. Always supply the complete desired list.
* An empty `targets` list clears the `pyck_workflow_targets` search attribute entirely.
* The workflow must be running and accessible in the Temporal cluster.
* The workflow's state object must implement the `WorkflowTargetsSetter` SDK interface from the pyck `workflowsdk` package.
* Updates are applied via Temporal's synchronous workflow update mechanism so they take effect immediately.
* After the mutation succeeds, subsequent `workflowExecutions` queries with `targets`/`targetsNotIn` predicates reflect the new state.
* Tenant isolation is enforced — only workflows in the caller's tenant can be modified.

## Related Documentation

* Query: [workflowTargets](/graphql-api/queries/workflowtargets.md)
* Input: [SetWorkflowTargetsInput](/graphql-api/inputs/setworkflowtargetsinput.md)
* Type: [SetWorkflowTargetsResponse](/graphql-api/types/setworkflowtargetsresponse.md)
* Enum: [WorkflowTarget](/graphql-api/enums/workflowtarget.md)
* Query: [workflowExecutions](/graphql-api/queries/workflowexecutions.md)

## Service

This mutation is provided by the **workflow** service as part of the federated GraphQL schema.


---

# 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/mutations/setworkflowtargets.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.