Replaying Failed Executions in Bulk

The replay-failed-executions example script wraps Prismatic's GraphQL API to replay an instance's failed executions. It finds every execution of the instance that failed, skips those that have already succeeded on a replay, and replays the rest.

Use it after you resolve the cause of a batch of failures, such as a third-party API outage or a payload format your integration didn't handle, to rerun each failed execution with its original input. This guide walks through the query and mutation the script sends, so you can adapt them to your own process. For background on replay and how it differs from automatic retry, see replaying failed executions.

Run the script

You need Node.js 22 or later, the Prism CLI tool logged in to your tenant, and the ID of the instance whose executions you want to replay. You can copy an instance's ID from the URL of its page in the web app.

Clone the examples repository, install dependencies, and preview the replays with --dry-run:

Preview which executions the script would replay

git clone https://github.com/prismatic-io/examples.git
cd examples/scripts/replay-failed-executions
npm install
npm run start -- --instance-id SW5zdGFuY2U6... --dry-run

The -- passes the options through npm to the script. With --dry-run, the script lists the executions it would replay without replaying them. Remove --dry-run to replay them:

Replay failed executions

npm run start -- --instance-id SW5zdGFuY2U6...

The start script gets an API token by running prism me:token, and sends each request with that token as a bearer token. To supply your own token instead, set PRISMATIC_API_KEY and run npx tsx index.ts with the same options. The script retries failed requests up to five times.

Requests go to https://app.prismatic.io/api by default. To use a tenant in another region, set PRISMATIC_URL to the region's URL from deployment regions, such as https://app.eu-west-1.prismatic.io.

Find failed executions

The script pages through the executionResults query for the instance:

Find an instance's failed executions and their successful replays

query getFailedExecutions($instanceId: ID!, $startCursor: String) {
  executionResults(
    instance: $instanceId
    error_Isnull: false
    replayForExecution_Isnull: true
    after: $startCursor
  ) {
    nodes {
      id
      startedAt
      replays(error_Isnull: true) {
        nodes {
          id
          startedAt
        }
      }
      error
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

The arguments narrow the results to the executions worth replaying:

Argument or field	Effect
instance	Returns executions of the specified instance
error_Isnull: false	Returns only executions that ended with an error
replayForExecution_Isnull: true	Excludes replays, so each result is an original execution
replays(error_Isnull: true)	For each original execution, returns its replays that succeeded

Prismatic links each replay to the execution it replays, which is what makes the last two filters possible. The script passes each response's pageInfo.endCursor as the next startCursor until hasNextPage is false.

After collecting every page, the script keeps only the executions whose replays.nodes array is empty. An execution with a successful replay doesn't need another one, so you can run the script again after a partial failure without replaying executions twice.

To replay a narrower set of executions, add other executionResults filters. For example, startedAt_Gte limits results to executions that started after a point in time, such as the start of an outage, and flow limits results to one flow. If you add filters or process results while paging, also add a sortBy argument so that pages stay consistent; see pagination.

Replay each execution

For each remaining execution, the script sends a replayExecution mutation:

Replay an execution

mutation ($executionId: ID!) {
  replayExecution(input: { id: $executionId }) {
    instanceExecutionResult {
      id
      startedAt
    }
  }
}

Prismatic starts a new execution of the instance with the original execution's input. The mutation returns the new execution's id and startedAt, which the script logs. It doesn't wait for the replay to finish, so check the replays on the instance's Executions tab or query them by ID to confirm they succeeded.

The script sends replays one at a time, in the order the query returned them. To report problems such as an execution that can't be replayed, add errors { field messages } to the mutation and check it in the response.