Graph Compose

Quickstart

Install the SDK, define a workflow, execute it, and query its status. By the end you will have a running workflow on Graph Compose.

Install

npm install @graph-compose/client

Authenticate

Every API call requires a token. Pass it to the constructor or set it as an environment variable.

Authentication

import { GraphCompose } from '@graph-compose/client'

// Option 1: pass in constructor
const graph = new GraphCompose({
  token: process.env.GRAPH_COMPOSE_TOKEN
})

// Option 2: set GRAPH_COMPOSE_TOKEN in your environment
// and the client picks it up automatically
const graph = new GraphCompose()

Find your API token under Settings » API Keys.

Build a workflow

This workflow fetches an order, checks inventory, and processes payment. Each node depends on the previous one, so they run in sequence.

import { GraphCompose } from '@graph-compose/client'

const graph = new GraphCompose({
  token: process.env.GRAPH_COMPOSE_TOKEN
})

graph
  .node("get_order")
    .get("https://api.example.com/orders/{{ context.orderId }}")
    .withRetries({
      maximumAttempts: 3,
      initialInterval: "1s"
    })
  .end()

  .node("check_inventory")
    .post("https://api.example.com/inventory/check")
    .withBody({
      items: "{{ results.get_order.data.items }}"
    })
    .withDependencies(["get_order"])
  .end()

  .node("process_payment")
    .post("https://api.example.com/payments")
    .withBody({
      orderId: "{{ results.get_order.data.id }}",
      amount: "{{ results.get_order.data.total }}"
    })
    .withDependencies(["check_inventory"])
    .withStartToCloseTimeout("30s")
  .end()

Three things to notice:

  • Dependencies control execution order. check_inventory waits for get_order to complete before running.
  • Template expressions pass data between nodes. {{ results.get_order.data.items }} accesses the response body from the get_order node. See Template Syntax for the full reference.
  • Activity config sets retry and timeout behavior per node. get_order retries up to 3 times; process_payment times out after 30 seconds.

Execute

Submit the workflow with context data. Graph Compose returns a workflow ID immediately and begins execution asynchronously.

Execute the Workflow

const result = await graph.execute({
  context: { orderId: "order_123" }
})

if (result.success && result.data) {
  console.log("Workflow ID:", result.data.workflowId)
  console.log("Run ID:", result.data.runId)
  console.log("Status:", result.data.status) // "RUNNING"
}

The context object becomes available to all nodes via {{ context.orderId }}.

Check status

Poll for completion or set a webhook to be notified.

Poll for Status

const workflowId = result.data.workflowId

let status = "RUNNING"
while (status === "RUNNING") {
  await new Promise(resolve => setTimeout(resolve, 2000))

  const check = await graph.getWorkflowStatus(workflowId)
  if (check.success && check.data) {
    status = check.data.status
  }
}

// Get final results
const final = await graph.getWorkflowStatus(workflowId)
if (final.success && final.data?.status === "COMPLETED") {
  console.log("Results:", final.data.execution_state)
}

Alternatively, pass a webhookUrl to receive a POST request when the workflow completes:

Using Webhooks

const result = await graph.execute({
  context: { orderId: "order_123" },
  webhookUrl: "https://api.example.com/webhook"
})

Workflow status can be: RUNNING, COMPLETED, FAILED, CANCELLED, TERMINATED, CONTINUED_AS_NEW, or TIMED_OUT.

Next steps

Core ConceptsNode TypesError BoundariesFlow ControlRetries and Timeouts