GraphQL API Overview

Data Index provides a GraphQL API for querying workflow instances and task executions.

Accessing the API

GraphQL Endpoint

POST http://data-index-service:8080/graphql
Content-Type: application/json

{
  "query": "{ ... }"
}

GraphQL UI (Development)

For interactive exploration:

http://data-index-service:8080/graphql-ui

Schema Overview

WorkflowInstance

Represents a workflow execution instance.

type WorkflowInstance {
  id: ID!
  name: String!
  namespace: String
  version: String
  status: WorkflowInstanceStatus!
  startDate: String
  endDate: String
  lastUpdate: String
  inputData: String      # JSON as string
  outputData: String     # JSON as string
  taskExecutions: [TaskExecution!]!
  error: WorkflowInstanceError
}

enum WorkflowInstanceStatus {
  RUNNING
  COMPLETED
  FAULTED
  CANCELLED
  SUSPENDED
}

type WorkflowInstanceError {
  type: String
  title: String
  detail: String
  status: Int
  instance: String
}

Field descriptions:

  • id - Unique workflow instance identifier (from Quarkus Flow)

  • name - Workflow name

  • namespace - Workflow namespace (optional)

  • version - Workflow version

  • status - Current instance status

  • startDate - ISO 8601 timestamp when instance started

  • endDate - ISO 8601 timestamp when instance ended (completed/faulted)

  • lastUpdate - ISO 8601 timestamp of last status change

  • inputData - Workflow input as JSON string

  • outputData - Workflow output as JSON string

  • taskExecutions - List of task executions within this instance

  • error - Error details if status is FAULTED

TaskExecution

Represents a task execution within a workflow instance.

type TaskExecution {
  id: ID!
  taskName: String!
  taskPosition: String!
  status: String!
  startDate: String
  endDate: String
  errorMessage: String
  inputData: String      # JSON as string
  outputData: String     # JSON as string
}

Field descriptions:

  • id - Unique task execution identifier

  • taskName - Name of the task (optional)

  • taskPosition - JSONPointer identifying task location in workflow (e.g., "/do/0", "/do/1/then/0")

  • status - Task status: RUNNING, COMPLETED, FAULTED

  • startDate - ISO 8601 timestamp when task started

  • endDate - ISO 8601 timestamp when task ended

  • errorMessage - Error message if status is FAULTED

  • inputData - Task input as JSON string

  • outputData - Task output as JSON string

Why String for JSON fields?

Input/output data is returned as JSON-encoded strings. Clients must parse the JSON themselves. This is a pragmatic solution - custom GraphQL scalars for JSON are complex with SmallRye GraphQL.

Queries

Get All Workflow Instances

Retrieve all workflow instances (with optional limit):

{
  getWorkflowInstances(limit: 10) {
    id
    name
    namespace
    status
    startDate
    endDate
    taskExecutions {
      taskName
      taskPosition
      status
    }
  }
}

Get Workflow Instance by ID

Retrieve a specific workflow instance:

{
  getWorkflowInstance(id: "01KQ7KGYQYHSG58PBSKTC2Y07Q") {
    id
    name
    status
    inputData
    outputData
    taskExecutions {
      taskName
      status
      inputData
      outputData
    }
  }
}

Filter Workflow Instances

Filter by status, name, namespace:

{
  getWorkflowInstancesByFilter(
    filter: {
      status: COMPLETED
      name: "petstore"
    }
  ) {
    id
    name
    version
    status
    startDate
    endDate
    lastUpdate
  }
}

Get Failed Workflows with Error Details

Retrieve failed workflows with complete error information:

{
  getWorkflowInstancesByFilter(filter: { status: FAULTED }) {
    id
    name
    status
    startDate
    endDate
    error {
      type
      title
      detail
      status
      instance
    }
    taskExecutions {
      taskPosition
      taskName
      status
      errorMessage
    }
  }
}

Query Examples

Example 1: List Recent Completions

curl -s http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ getWorkflowInstances(limit: 5) { id name status endDate } }"
  }' | jq .

Response:

{
  "data": {
    "getWorkflowInstances": [
      {
        "id": "01KQ7KGYQYHSG58PBSKTC2Y07Q",
        "name": "simple-set",
        "status": "COMPLETED",
        "endDate": "2026-04-27T18:55:29.065Z"
      }
    ]
  }
}

Example 2: Get Workflow with Task Details

curl -s http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ getWorkflowInstance(id: \"01KQ7KGYQYHSG58PBSKTC2Y07Q\") { id name status taskExecutions { taskPosition status startDate endDate } } }"
  }' | jq .

Response:

{
  "data": {
    "getWorkflowInstance": {
      "id": "01KQ7KGYQYHSG58PBSKTC2Y07Q",
      "name": "simple-set",
      "status": "COMPLETED",
      "taskExecutions": [
        {
          "taskPosition": "do/0/set-0",
          "status": "COMPLETED",
          "startDate": "2026-04-27T18:55:29.057Z",
          "endDate": "2026-04-27T18:55:29.061Z"
        },
        {
          "taskPosition": "do/1/set-1",
          "status": "COMPLETED",
          "startDate": "2026-04-27T18:55:29.061Z",
          "endDate": "2026-04-27T18:55:29.065Z"
        }
      ]
    }
  }
}

Example 3: Parse JSON Input/Output

curl -s http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ getWorkflowInstance(id: \"01KQ7KGYQYHSG58PBSKTC2Y07Q\") { inputData outputData } }"
  }' | jq -r '.data.getWorkflowInstance | {input: (.inputData | fromjson), output: (.outputData | fromjson)}'

Response:

{
  "input": {
    "name": "E2E Test"
  },
  "output": {
    "completed": true,
    "mode": "PostgreSQL"
  }
}

Filtering

The GraphQL API supports filtering on:

  • status: Filter by workflow status (RUNNING, COMPLETED, FAULTED, CANCELLED, SUSPENDED)

  • name: Filter by workflow name (exact match)

  • namespace: Filter by workflow namespace (exact match)

Future enhancements:

  • JSON path filtering (e.g., filter by input.orderId)

  • Time range filtering (e.g., startDate between X and Y)

  • Sorting options

Error Handling

GraphQL errors are returned in the errors field:

{
  "errors": [
    {
      "message": "Workflow instance not found: invalid-id",
      "locations": [...],
      "path": ["getWorkflowInstance"]
    }
  ]
}

Next Steps