---
title: "Get Edge"
method: GET
path: "/workflows/v1/edges/{edge_id}"
tags: ["Edges"]
---

# Get Edge

`GET /workflows/v1/edges/{edge_id}`

Endpoint to retrieve an edge configuration by its ID.
Optionally verify the edge belongs to a specific version.

## Path parameters

- `edge_id` string, required

## Query parameters

- `version_number` integer, nullable — Verify edge belongs to this version number (0 includes legacy edges)

## Response `200`

Successful Response

- EdgesResponse — Response model for a single edge. Contains an EdgesModel object.
  - `edge` EdgesModel, required — Stores an edge configuration present in the workflow system.
    - `team_id` string, nullable — ID of the team that owns this edge
    - `created_by` string, nullable — ID of the user who created this edge
    - `updated_by` string, nullable — ID of the user who last updated this edge
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `_id` string
    - `edge_config` union — Edge Configuration
      - DirectEdgeConfigOutput
        - `logical_id` string, nullable — Unique identifier for the edge
        - `name` string, nullable — Name of the edge
        - `description` string, nullable — Description of the edge
        - `workflow_id` string, nullable — The DB Object ID of the workflow this entity belongs to
        - `version_number` integer, nullable — Version number of the workflow this entity belongs to. 0 is the initial version (default).
        - `disabled` boolean — If true, this entity will be disabled and will not execute its function. Useful for testing workflows without actually executing this specific entity
        - `miscellaneous` object — Miscellaneous config data that can be used by the entity
        - `source_node_logical_id` string, nullable — Logical ID of the source node for this edge
        - `destination_node_logical_id` string, nullable — Logical ID of the target node for this edge
        - `type` 'direct' — Type of the edge. Expected to be always 'direct' for this base config
        - `companion_thread_config` CompanionThreadConfig — Compound companion-thread settings for a direct edge, grouping the two related fields so their relationship is explicit in the authoring UI and the stored config.
          - `is_companion_thread` boolean — When a node has multiple outgoing direct edges, edges with this flag set to True spawn companion threads that run alongside the single main thread (the one edge with this flag False). Companion threads keep executing and emitting events while the main thread waits for user input, and never receive UI user messages. A lone direct edge always continues the main thread regardless of this flag.
          - `thread_id` string, nullable — Author-chosen id for the forked companion thread. Other threads read this companion's runtime variables via [[thread_<thread_id>.<var>]], and the companion reads the main thread via [[thread_0.<var>]]. Must be unique across the workflow's companion edges, non-empty, and use only [A-Za-z0-9_-] (no '.', no '_companion_', and not the reserved id '0'). Optional: if omitted, a uuid is generated at fork time and the companion is not addressable via a cross-thread reference.
      - ConditionalEdgeConfigOutput
        - `logical_id` string, nullable — Unique identifier for the edge
        - `name` string, nullable — Name of the edge
        - `description` string, nullable — Description of the edge
        - `workflow_id` string, nullable — The DB Object ID of the workflow this entity belongs to
        - `version_number` integer, nullable — Version number of the workflow this entity belongs to. 0 is the initial version (default).
        - `disabled` boolean — If true, this entity will be disabled and will not execute its function. Useful for testing workflows without actually executing this specific entity
        - `miscellaneous` object — Miscellaneous config data that can be used by the entity
        - `source_node_logical_id` string, nullable — Logical ID of the source node for this edge
        - `destination_node_logical_id` string, nullable — Logical ID of the target node for this edge
        - `type` 'conditional' — Type of the edge. Expected to be always 'conditional' for this config
        - `condition` ConditionConfig
          - `condition_freeform` string, nullable — Condition (expressed in natural language) that determines whether this path is taken
          - `condition_expression` string, nullable — Condition (expressed in a structured equation with variables) that determines whether this path is taken
          - `args_schema` object, nullable — JSON Schema describing the arguments that will be passed when condition_freeform is evaluated
          - `static_messages_config` StaticMessagesConfig
            - `static_messages` string[] — List of pre-configured messages from which one will be emitted
            - `static_messages_selection_mode` 'random' | 'sequence'
          - `dynamic_messages_config` DynamicMessagesConfig
            - `dynamic_message_prompt` string, nullable — A prompt describing what the LLM should say when this conditional edge is taken. The LLM will be asked to fill in a value based on this prompt, and the result will be emitted as an assistant response.
        - `evaluate_while_waiting_config` EvaluateWhileWaitingConfig — Opt-in: evaluate this conditional edge's ``condition_expression`` while the SOURCE node is parked waiting for a user message, and take the edge if it becomes True — with no user message required. Without this config a conditional edge is evaluated at exactly one moment: immediately after each execution of its source node. A ``say_llm`` node with ``self_loop`` + ``wait_for_user_message`` therefore parks indefinitely, and a runtime variable that flips in the background (e.g. written by a polling node in a companion thread) cannot move the conversation forward on its own. Only valid on an edge whose condition uses ``condition_expression``; ``condition_freeform`` conditions need an LLM call per evaluation and are rejected rather than silently ignored. See ``WorkflowRuntime._validate_waiting_evaluated_edges`` for the full validation matrix.
          - `enabled` boolean — When True, this edge is also evaluated while its source node is parked waiting for user input, and is taken if the expression becomes True.
          - `trigger_mode` 'on_node_completion' | 'on_every_background_tick' — What arms an evaluation of a conditional edge while its source node waits for user input.
          - `trigger_node_logical_ids` string[] — Node logical ids whose completion arms one evaluation of this edge. Required when trigger_mode is 'on_node_completion'. Nodes may live in any thread — typically a companion-thread node that updates the runtime variable this expression reads.
          - `min_seconds_between_evaluations` number, nullable — Debounce: an armed evaluation waits until this many seconds after the previous one. REQUIRED (and must be > 0) when trigger_mode is 'on_every_background_tick', because that mode is always armed — without a debounce it would evaluate on every background pass, spinning the driver loop and flooding the run record. Optional for 'on_node_completion', which is already bounded by how often the trigger node completes. 0 means no debounce and is only meaningful for 'on_node_completion'.
          - `max_transitions_per_wait` integer — Hard bound on how many times this edge may fire during a single uninterrupted wait (reset when a user message is received). Guards against background hop loops in which no user is ever given a turn.
      - CompanionEdgeConfigOutput
        - `logical_id` string, nullable — Unique identifier for the edge
        - `name` string, nullable — Name of the edge
        - `description` string, nullable — Description of the edge
        - `workflow_id` string, nullable — The DB Object ID of the workflow this entity belongs to
        - `version_number` integer, nullable — Version number of the workflow this entity belongs to. 0 is the initial version (default).
        - `disabled` boolean — If true, this entity will be disabled and will not execute its function. Useful for testing workflows without actually executing this specific entity
        - `miscellaneous` object — Miscellaneous config data that can be used by the entity
        - `source_node_logical_id` string, nullable — Logical ID of the source node for this edge
        - `destination_node_logical_id` string, nullable — Logical ID of the target node for this edge
        - `type` 'companion' — Type of the edge. Expected to be always 'companion' for this config

## Other responses

- `422` — Validation Error

## Changes

- **2026-07-31** `65c85b75b3bc` — 2 info
  - added the optional property `edge/edge_config/anyOf[subschema #1]/oneOf[subschema #1: Direct Edge]/companion_thread_config` to the response with the `200` status
  - added the optional property `edge/edge_config/anyOf[subschema #1]/oneOf[subschema #2: Conditional Edge]/evaluate_while_waiting_config` to the response with the `200` status

[Change history](https://skmtc.dev/interactly/apis/interactly-api-3/changes/workflows/v1/edges/:edge_id/get.md)

---

[API](https://skmtc.dev/interactly/apis/interactly-api-3.md) · [All operations](https://skmtc.dev/interactly/apis/interactly-api-3/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/interactly/interactly-api-3/revisions/35cbea12a781/schema)