Calling Workflows from the API

Overview

The gaiia GraphQL API exposes queries and mutations for triggering workflows programmatically, retrieving execution status, managing in-flight executions, exporting workflow definitions, and managing workflow variables and secrets. In this article, we'll be covering the available operations, their inputs and error codes, the types they return, and example queries to get you started.

Query workflow definitions

Use these queries to list workflows, retrieve specific definitions, and export workflow configuration for version control or auditing.

workflows

List all workflows with optional filtering, ordering, and cursor-based pagination.

workflows(
  first: Int
  last: Int
  after: String
  before: String
  filter: WorkflowFilter
  orderBy: [WorkflowOrderBy!]
): WorkflowConnection!

first / after — forward pagination: return up to first results after the cursor.
last / before — backward pagination: return up to last results before the cursor.
filter — see WorkflowFilter for available filters.
orderBy — see WorkflowOrderBy for ordering options.

Returns a WorkflowConnection with edges, nodes, pageInfo, and totalCount.

workflowDefinition

Fetch a single workflow definition by its Global ID.

workflowDefinition(id: GlobalID!): WorkflowDefinition

id — the workflow definition's Global ID (required).

Returns a WorkflowDefinition object, or null if not found.

Access full workflow definition JSON

Every WorkflowDefinition includes a representationJson field that returns the complete JSON structure of the workflow, including triggers, steps, conditions, loops, and configuration. This JSON can be used for version control, auditing, or re-importing workflows.

query GetWorkflowDefinition($id: GlobalID!) {
  workflowDefinition(id: $id) {
    id
    version
    createdAt
    representationJson
  }
}

The representationJson structure is considered unstable and may change between gaiia releases. Use it as an opaque interchange format for exporting and importing workflows, not as a stable schema to build parsers around.

Query workflows and executions

Use these queries to look up workflow definitions and execution records.

workflow

Fetch a single workflow by its Global ID.

workflow(id: GlobalID!): Workflow

id — the workflow's Global ID (required).

Returns a Workflow object, or null if not found.

workflowExecution

Fetch a single workflow execution by its Global ID.

workflowExecution(id: GlobalID!): WorkflowExecution

id — the workflow execution's Global ID (required).

Returns a WorkflowExecution object, or null if not found.

workflowExecutions

List workflow executions with optional filtering, ordering, and cursor-based pagination.

workflowExecutions(
  first: Int
  last: Int
  after: String
  before: String
  filter: WorkflowExecutionFilter
  orderBy: [WorkflowExecutionOrderBy!]
): WorkflowExecutionConnection!

first / after — forward pagination: return up to first results after the cursor.
last / before — backward pagination: return up to last results before the cursor.
filter — see Filter executions below.
orderBy — see Order executions below.

Returns a WorkflowExecutionConnection with edges, nodes, pageInfo, and totalCount.

Filter executions

WorkflowExecutionFilter - narrows down the workflowExecutions query

WorkflowNodeExecutionFilter - filter node executions within a WorkflowExecution

Order executions

Pass a WorkflowExecutionOrderBy array to control result ordering.

direction: OrderByDirection! — ASC or DESC.
field: WorkflowExecutionOrderByField! — available values: CREATED_AT, STATUS.

To order node executions, pass a WorkflowNodeExecutionOrderBy to nodeExecutions:

field: WorkflowNodeExecutionOrderByField! — available values: UPDATED_AT.

Inspect node execution results

Use these queries to retrieve detailed execution data for individual workflow nodes.

workflowNodeExecution

Fetch a single workflow node execution by its Global ID.

workflowNodeExecution(id: GlobalID!): WorkflowNodeExecution

id — the workflow node execution's Global ID (required).

Returns a WorkflowNodeExecution object, or null if not found.

workflowNodeExecutionResult

Fetch the output result of a workflow node execution.

workflowNodeExecutionResult(id: GlobalID!): WorkflowNodeExecutionResult

id — the workflow node execution result's Global ID (required).

Returns a WorkflowNodeExecutionResult object containing the node's output data, or null if not found.

Manage variables and secrets

Use these mutations to programmatically create, update, and delete workflow-scoped variables and secrets. Variables store non-sensitive configuration like base URLs, while secrets store encrypted sensitive data like API tokens.

createWorkflowVariable

Create a new workflow variable.

createWorkflowVariable(input: CreateWorkflowVariableInput!): CreateWorkflowVariableResult!

Input fields:

key: String! — the variable key (maximum 255 characters).
value: String! — the variable value (maximum 10,000 characters).

Result fields:

workflowVariable: WorkflowVariable — the created variable, if successful.
errors: [CreateWorkflowVariableError!]! — expected errors, if any.

Error codes:

DUPLICATE_ENTRY — a variable with the same key already exists.

updateWorkflowVariable

Update an existing workflow variable.

updateWorkflowVariable(id: GlobalID!, input: UpdateWorkflowVariableInput!): UpdateWorkflowVariableResult!

Input fields:

id: GlobalID! — the Global ID of the variable to update.
key: String — the updated key (optional).
value: String — the updated value (optional).

Result fields:

workflowVariable: WorkflowVariable — the updated variable, if successful.
errors: [UpdateWorkflowVariableError!]! — expected errors, if any.

Error codes:

DUPLICATE_ENTRY — the updated key already exists.
WORKFLOW_VARIABLE_NOT_FOUND — no variable was found for the provided ID.

deleteWorkflowVariable

Delete a workflow variable.

deleteWorkflowVariable(id: GlobalID!): DeleteWorkflowVariableResult!

Input fields:

id: GlobalID! — the Global ID of the variable to delete.

Result fields:

workflowVariable: WorkflowVariable — the deleted variable, if successful.
errors: [DeleteWorkflowVariableError!]! — expected errors, if any.

Error codes:

WORKFLOW_VARIABLE_NOT_FOUND — no variable was found for the provided ID.

createWorkflowSecret

Create a new workflow secret.

createWorkflowSecret(input: CreateWorkflowSecretInput!): CreateWorkflowSecretResult!

Input fields:

key: String! — the secret key (maximum 255 characters).
value: String! — the secret value, which will be encrypted (maximum 10,000 characters).

Result fields:

workflowSecret: WorkflowSecret — the created secret, if successful.
errors: [CreateWorkflowSecretError!]! — expected errors, if any.

Error codes:

DUPLICATE_ENTRY — a secret with the same key already exists.

updateWorkflowSecret

Update an existing workflow secret.

updateWorkflowSecret(id: GlobalID!, input: UpdateWorkflowSecretInput!): UpdateWorkflowSecretResult!

Input fields:

id: GlobalID! — the Global ID of the secret to update.
key: String — the updated key (optional).
value: String — the updated value, which will be encrypted (optional).

Result fields:

workflowSecret: WorkflowSecret — the updated secret, if successful.
errors: [UpdateWorkflowSecretError!]! — expected errors, if any.

Error codes:

DUPLICATE_ENTRY — the updated key already exists.
WORKFLOW_SECRET_NOT_FOUND — no secret was found for the provided ID.

deleteWorkflowSecret

Delete a workflow secret.

deleteWorkflowSecret(id: GlobalID!): DeleteWorkflowSecretResult!

Input fields:

id: GlobalID! — the Global ID of the secret to delete.

Result fields:

workflowSecret: WorkflowSecret — the deleted secret, if successful.
errors: [DeleteWorkflowSecretError!]! — expected errors, if any.

Error codes:

WORKFLOW_SECRET_NOT_FOUND — no secret was found for the provided ID.

Start an execution

Use the startWorkflowExecution mutation to trigger a workflow programmatically. The workflow must be enabled and the provided input must satisfy its trigger input schema.

startWorkflowExecution(input: StartWorkflowExecutionInput!): StartWorkflowExecutionResult!

Input fields

workflowId: GlobalID! — the Global ID of the workflow to start.
input: JSON — the trigger input to pass to the workflow. Must satisfy the workflow's input schema if one is defined.
objectId: GlobalID — the Global ID of a gaiia object to associate with this execution (e.g. an account). When set, the execution appears on that object's Workflows tab.
correlationId: String — an optional UUID to track this execution across systems. If omitted, one is generated automatically.

Result fields

workflowExecution: WorkflowExecution — the created execution, if successful.
errors: [StartWorkflowExecutionError!]! — expected errors, if any.

Error codes

INTEGRATION_NOT_INSTALLED — the integration associated with this workflow is not installed.
INVALID_INPUT_SCHEMA — the provided input does not satisfy the workflow's trigger input schema.
WORKFLOW_DISABLED — the workflow is currently disabled.
WORKFLOW_NOT_FOUND — no workflow was found for the provided ID.

Cancel an execution

Use the cancelWorkflowExecution mutation to cancel a workflow execution that is in progress. Cancellation is only possible while the execution is in a cancellable status.

cancelWorkflowExecution(input: CancelWorkflowExecutionInput!): CancelWorkflowExecutionResult!

Input fields

workflowExecutionId: GlobalID! — the Global ID of the execution to cancel.
reason: String — an optional reason for the cancellation.

Result fields

workflowExecution: WorkflowExecution — the execution in its updated state.
errors: [CancelWorkflowExecutionError!]! — expected errors, if any.

Error codes

INVALID_WORKFLOW_EXECUTION_STATUS — the execution cannot be cancelled because of its current status.
WORKFLOW_EXECUTION_NOT_FOUND — no execution was found for the provided ID.

Retry an execution

Use the retryWorkflowExecution mutation to retry a failed workflow execution from the point of failure.

retryWorkflowExecution(input: RetryWorkflowExecutionInput!): RetryWorkflowExecutionResult!

Input fields

workflowExecutionId: GlobalID! — the Global ID of the execution to retry.

Result fields

workflowExecution: WorkflowExecution — the execution in its updated state.
errors: [RetryWorkflowExecutionError!]! — expected errors, if any.

Error codes

INVALID_WORKFLOW_EXECUTION_STATUS — the execution cannot be retried because of its current status.
WORKFLOW_EXECUTION_NOT_FOUND — no execution was found for the provided ID.

Understand the returned types

Workflow - Represents a workflow definition
WorkflowExecutionEdge - Represents a single run of a workflow
WorkflowNodeExecution - Represents the execution of a single node within a workflow execution
WorkflowExecutionObject - A union of the gaiia object types that can be associated with a workflow execution

Status enums

Try these examples

Export a workflow definition for version control

query ListWorkflowsWithDefinitions {
  workflows(first: 100, filter: { isEnabled: { equals: true } }) {
    nodes {
      id
      key
      name
      latestDefinition {
        id
        version
        representationJson
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Create a workflow variable

mutation CreateVariable {
  createWorkflowVariable(
    input: {
      key: "API_BASE_URL"
      value: "https://api.example.com"
    }
  ) {
    workflowVariable {
      id
      key
      value
    }
    errors {
      code
      message
    }
  }
}

Start a workflow execution

mutation StartWorkflowExecution($accountNumber: String!) {
  startWorkflowExecution(
    input: {
      workflowId: "workflow_bLx9Q2B3DzrTJHQ75aPpLV",
      input: { accountNumber: $accountNumber }
    }
  ) {
    workflowExecution {
      id
      status
      correlationId
    }
    errors {
      code
      message
    }
  }
}

List recent executions for an object

query {
  workflowExecutions(
    first: 10
    filter: {
      object: { id: { equals: "account_cktryRfyFDoTdxaSNcnbWA" } }
      status: { in: [IN_PROGRESS, FAILED] }
    }
    orderBy: [{ field: CREATED_AT, direction: DESC }]
  ) {
    nodes {
      id
      status
      createdAt
      definition {
        workflow {
          name
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Fetch node executions for an execution

query {
  workflowExecution(id: "workflow_execution_dqzzbcJm5RHXB5UKfzWjav") {
    id
    status
    nodeExecutions(
      filter: { status: { in: [FAILED] } }
      orderBy: [{ field: UPDATED_AT, direction: ASC }]
    ) {
      nodes {
        id
        status
        startTime
        endTime
        executionTimeInMs
        errorData
      }
    }
  }
}

Cancel a workflow execution

mutation {
  cancelWorkflowExecution(
    input: {
      workflowExecutionId: "workflow_execution_dqzzbcJm5RHXB5UKfzWjav"
      reason: "Triggered by mistake"
    }
  ) {
    workflowExecution {
      id
      status
    }
    errors {
      code
      message
    }
  }
}

Related to

Workflows

Overview

Query workflow definitions

workflows

workflowDefinition

Access full workflow definition JSON

Query workflows and executions

workflow

workflowExecution

workflowExecutions

Filter executions

Order executions

Inspect node execution results

workflowNodeExecution

workflowNodeExecutionResult

Manage variables and secrets

createWorkflowVariable

updateWorkflowVariable

deleteWorkflowVariable

createWorkflowSecret

updateWorkflowSecret

deleteWorkflowSecret

Start an execution

Input fields

Result fields

Error codes

Cancel an execution

Input fields

Result fields

Error codes

Retry an execution

Input fields

Result fields

Error codes

Understand the returned types

Status enums

Try these examples

Export a workflow definition for version control

Create a workflow variable

Start a workflow execution

List recent executions for an object

Fetch node executions for an execution

Cancel a workflow execution

Was this article helpful?

Documentation

<% if (!imageHeight) { %> <%= block.name %> <% } else { %> <%= block.name %> <% } %>

<% if (block.html_url) { %> <%= block.name %> <% } else { %> <%= block.name %> <% } %>

Limited access

Product page

Sign in

Navigation

Navigation

<%= heading %>

<%= article.title %>