> ## Documentation Index > Fetch the complete documentation index at: https://docs.zeroset.com/llms.txt > Use this file to discover all available pages before exploring further. # Workflows > Workflow read APIs for observed workflow instances and mined patterns Nebula exposes read APIs for observed workflow instances and mined workflow patterns: ```txt theme={null} 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 ```txt theme={null} 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: ```json theme={null} { "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 ```txt theme={null} 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: ```json theme={null} { "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 ```txt theme={null} 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: ```json theme={null} { "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 ```txt theme={null} 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: ```json theme={null} { "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.