Workflows

Nebula exposes read APIs for observed workflow instances and mined workflow patterns:

GET /v1/workflows
GET /v1/workflows/{instance_id}
GET /v1/workflow-patterns
GET /v1/workflow-patterns/{pattern_id}

These endpoints require the same authentication as other Nebula APIs and are scoped by collection_id. The caller must have access to the requested collection. Workflow reads are served by Nebula’s graph read backend; deployments without that backend configured return 503.

These endpoints are hidden from the generated OpenAPI schema while the workflow-pattern product surface is maturing. Response changes should be additive unless a release note says otherwise.

Workflow instances

A workflow instance is an observed execution chain in a collection. Nebula derives instances from procedure traces and the before/after state transitions between them. Instances can exist with or without a mined workflow pattern. The instance id is the root trace UUID for the execution chain. current_state_description is the latest observed state summary, and trace_count is the number of procedure traces currently associated with the instance.

List instances

GET /v1/workflows?collection_id=COLLECTION_UUID

Query parameter	Type	Default	Description
`collection_id`	`uuid`	Required	Collection to read from.
`pattern_id`	`uuid`	None	Return only instances linked to this workflow pattern.
`include_unpatterned`	`boolean`	`true`	When `pattern_id` is omitted, include instances that are not linked to a mined pattern.
`offset`	`integer`	`0`	Page offset. Must be `>= 0`.
`limit`	`integer`	`25`	Page size. Must be between `1` and `100`.

Response:

{
  "results": [
    {
      "id": "INSTANCE_UUID",
      "collection_id": "COLLECTION_UUID",
      "pattern_id": "PATTERN_UUID",
      "current_state_description": "Waiting for security review",
      "last_activity_at": "2026-05-27T18:30:00Z",
      "trace_count": 4
    }
  ],
  "total_entries": 1
}

Retrieve an instance

GET /v1/workflows/{instance_id}?collection_id=COLLECTION_UUID

Query parameter	Type	Default	Description
`collection_id`	`uuid`	Required	Collection to read from.
`history_limit`	`integer`	`20`	Maximum number of state-history entries to return. Must be between `1` and `200`.
`similar_limit`	`integer`	`5`	Maximum number of sibling instances from the same pattern to return. Must be between `0` and `25`.

instance_id is normally the root trace UUID returned by GET /v1/workflows. The endpoint also accepts a trace UUID inside the instance and resolves it to the containing workflow. Response:

{
  "results": {
    "id": "INSTANCE_UUID",
    "collection_id": "COLLECTION_UUID",
    "pattern_id": "PATTERN_UUID",
    "current_state_description": "Waiting for security review",
    "last_activity_at": "2026-05-27T18:30:00Z",
    "trace_count": 4,
    "current_state": {
      "node_id": "STATE_UUID",
      "description": "Waiting for security review",
      "entered_at": "2026-05-27T18:30:00Z",
      "members": {
        "entities": [
          { "id": "ENTITY_UUID", "name": "SOC2 review" }
        ],
        "facts": [
          {
            "id": "FACT_UUID",
            "predicate": "status",
            "subject": "SOC2 review",
            "object": "waiting",
            "description": "SOC2 review is waiting on security approval."
          }
        ]
      }
    },
    "position": { "step": 3, "of": 5 },
    "history": [
      {
        "state": {
          "node_id": "STATE_UUID",
          "description": "Security review requested",
          "entered_at": null,
          "members": { "entities": [], "facts": [] }
        },
        "trace": null
      },
      {
        "state": {
          "node_id": "STATE_UUID",
          "description": "Waiting for security review",
          "entered_at": "2026-05-27T18:30:00Z",
          "members": { "entities": [], "facts": [] }
        },
        "trace": {
          "id": "TRACE_UUID",
          "verb_class": "request",
          "description": "Requested security review",
          "occurred_at": "2026-05-27T18:30:00Z",
          "extraction_confidence": 0.92
        }
      }
    ],
    "history_truncated": false,
    "similar_instances": [
      {
        "id": "OTHER_INSTANCE_UUID",
        "pattern_id": "PATTERN_UUID",
        "current_state_description": "Security review approved",
        "last_activity_at": "2026-05-26T16:15:00Z"
      }
    ]
  }
}

position is present only when the instance is linked to a mined pattern. step is the 1-indexed current state position in the observed chain, and of is the expected state count from the pattern. history_truncated is true when older entries were omitted by history_limit.

Workflow patterns

Workflow patterns are mined from Nebula’s state-and-trace graph. The mining pass looks for repeated chains of procedure traces connected by before/after state transitions. Equivalent chains are grouped into a canonical signature, and confidence is derived from recurrence and graph evidence. Use workflow patterns as advisory structure: good for cursoring, resuming, evidence, and bootstrap hints. Do not treat a pattern as an exclusive source of truth for whether a workflow can occur.

List patterns

GET /v1/workflow-patterns?collection_id=COLLECTION_UUID

Query parameter	Type	Default	Description
`collection_id`	`uuid`	Required	Collection to read from.
`offset`	`integer`	`0`	Page offset. Must be `>= 0`.
`limit`	`integer`	`25`	Page size. Must be between `1` and `100`.

Response:

{
  "results": [
    {
      "id": "PATTERN_UUID",
      "collection_id": "COLLECTION_UUID",
      "name": "Security review workflow",
      "description": "Review request moves through assignment, approval, and completion.",
      "confidence": 0.87,
      "instance_count": 12,
      "pattern_size": 5
    }
  ],
  "total_entries": 1
}

Retrieve a pattern

GET /v1/workflow-patterns/{pattern_id}?collection_id=COLLECTION_UUID

Query parameter	Type	Default	Description
`collection_id`	`uuid`	Required	Collection to read from.
`instance_offset`	`integer`	`0`	Offset into the pattern’s linked instance IDs. Must be `>= 0`.
`instance_limit`	`integer`	`25`	Maximum linked instance IDs to return. Must be between `1` and `200`.

Response:

{
  "results": {
    "id": "PATTERN_UUID",
    "collection_id": "COLLECTION_UUID",
    "name": "Security review workflow",
    "description": "Review request moves through assignment, approval, and completion.",
    "confidence": 0.87,
    "instance_count": 12,
    "pattern_size": 5,
    "canonical_signature": "request>assign>approve>complete",
    "weighted_frequency": 9.4,
    "canonical_instance_id": "INSTANCE_UUID",
    "instance_ids": ["INSTANCE_UUID", "OTHER_INSTANCE_UUID"],
    "instance_ids_total": 12
  }
}

Stable fields for consumers:

Field	Meaning
`id`	Pattern UUID.
`name` / `description`	Human-readable summary of the mined pattern.
`confidence`	Confidence in `[0, 1]` derived from recurrence/evidence.
`instance_count`	Number of workflow instances linked to the pattern.
`pattern_size`	Approximate structural size of the pattern.
`canonical_signature`	Debuggable signature of the trace/connectivity chain.
`instance_ids`	Paginated workflow instance UUIDs linked to the pattern detail.

canonical_signature is useful for diagnostics and deduplication, but product clients should prefer id, confidence, and linked instances for durable behavior.

Get Started

Kubernetes

Docker Compose

Connectors

Reference

Workflow instances

List instances

Retrieve an instance

Workflow patterns

List patterns

Retrieve a pattern

​Workflow instances

​List instances

​Retrieve an instance

​Workflow patterns

​List patterns

​Retrieve a pattern

Workflow instances

List instances

Retrieve an instance

Workflow patterns

List patterns

Retrieve a pattern