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}
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. |
{
"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. |
{
"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. |
{
"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
}
}
| 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. 
