---
agentTools:
  projectIndex: https://developers.pipefy.com/llms.txt
---

# Simulate Automation Execution

How to simulate an automation and retrieve the simulation result using GraphQL

## Overview

This guide explains how to **simulate an automation execution** using Pipefy's GraphQL API. The process involves two steps:

1. **Create a simulation** using the `createAutomationSimulation` mutation.
2. **Retrieve the simulation result** using the `automationSimulation` query.

This flow allows you to test automation logic and preview results before applying changes.

## Prerequisites

1. **Authentication**: Use a [Service Account token](https://developers.pipefy.com/reference/service-accounts).
2. **Permissions**: Ensure your token has permission to simulate automations.
3. **Automation Input**: Prepare the input data required for the simulation (such as event and action parameters).

## Step 1: Create an Automation Simulation

Use the `createAutomationSimulation` mutation to start a simulation. You must provide the required input for the automation.

```graphql
mutation CreateAutomationSimulation($input: CreateAutomationSimulationInput!) {
  createAutomationSimulation(input: $input) {
    simulationId
  }
}
```

**Variables example:**

```json
{
  "input": {
    "action_id": "generate_with_ai",
    "action_repo_id": "2",
    "action_params": {
      "aiParams": {
        "fieldIds": ["123", "321"],
        "value": "Read field ${123} and translate it"
      }
    },
    "sampleCardId": "203"
  }
}
```

### Key Fields Returned

* **`simulationId`**: The unique identifier for the simulation. Use this to query the simulation result.

## Step 2: Retrieve the Automation Simulation Result

After creating the simulation, use the `automationSimulation` query to check the status and retrieve the result.

```graphql
query AutomationSimulation($simulationId: ID!) {
  automationSimulation(simulationId: $simulationId) {
    simulationResult
    details {
      errorType
      message
    }
    status
  }
}
```

**Variables example:**

```json
{
  "simulationId": "the-id-returned-by-mutation"
}
```

### Key Fields Returned

* **`simulationResult`**: The result of the simulation (may be a JSON object with simulated output).
* **`details`**: Additional details, such as error type and message if applicable.
* **`status`**: The current status (`processing`, `success`, `failed`).

## Example Flow

1. **Run the mutation** to create a simulation and note the returned `simulationId`.
2. **Poll the query** with the `simulationId` until `status` is `success` or `failed`.
3. **Review the `simulationResult`** and `details` fields for the outcome.

## Example Response (Mutation)

```json
{
  "data": {
    "createAutomationSimulation": {
      "simulationId": "simulation-uuid-123"
    }
  }
}
```

## Example Response (Query)

```json
{
  "data": {
    "automationSimulation": {
      "simulationResult": {
        "fieldId": "simulated value"
      },
      "details": {
        "errorType": null,
        "message": "Simulation completed successfully."
      },
      "status": "success"
    }
  }
}
```

## Notes

* The simulation process may take some time. Poll the query until the status is `success` or `failed`.
* If the simulation fails, check the `details` or `errorMessage` fields for more information.
* Use simulation to validate automation logic before deploying