Skip to main content

Execution Order

Execution order is the sequence in which endpoints run during a collection. Understanding and managing it ensures dependencies are satisfied and data flows correctly. Traces surfaces order in two complementary ways: the endpoint tree (which shows each enabled endpoint's order number) and execution phases (a higher-level grouping built in the Bulk tab and shown in the Phase Index panel).

Overview​

The underlying order is computed automatically from your dependency mappings:

  1. Dependencies: An endpoint that consumes another endpoint's data runs after its source
  2. Preferred order: Your manual ordering is honored wherever it doesn't violate a dependency
  3. Default order: Endpoints with no dependencies keep their natural order

The order calculation (calculateExecutionOrder / calculateExecutionOrderPreferring in lib/graph/execution-order.ts) is a dependency-respecting topological sort. A custom order is stored only when you reorder manually; otherwise the derived topological order is used directly.

The Endpoint Tree​

In both editor trees, the left-hand endpoint tree (EndpointTreeNavigator) shows the endpoints with:

  • An order number reflecting the computed execution position
  • A test status indicator (pending / testing / tested / error)
  • Enable/disable toggles (eye / eye-off)
  • A tested progress summary in the header (e.g. "8 / 12 tested (67%)") with a "next untested" shortcut

Disabled endpoints are excluded from the execution order and the test-progress counts.

Execution Phases​

For larger connectors, endpoints can be grouped into phases and stages:

  • A phase is a named, ordered group (e.g. "Discovery", "Detail fetch").
  • A stage is a named group of endpoints within a phase. Endpoints in the same stage have no dependency between them and can be treated as a parallel batch.

Phases are not present by default. They are created from the Bulk tab on the connector edit page using Reorder with AI, which groups endpoints into phases/stages based on their dependencies. You can then rename, add, delete, and reorder phases and stages, and drag endpoints between stages.

Phase Index Panel​

When a connector has phases, the published connector edit page shows the Phase Index panel (PhaseIndexPanel) on the left instead of the flat tree:

  • Each phase is listed with its stages and their endpoints
  • A phase shows a tested-count summary and is marked complete when all its endpoints are tested
  • Clicking a phase or endpoint focuses it
  • If a connector has no phases yet, the panel prompts you to use Reorder with AI in the Bulk tab

Phase Order Validation​

Because phases impose an explicit order, they can conflict with dependency mappings. Traces validates the proposed phase order against all mappings:

  • A violation occurs when an endpoint's data source is scheduled after the endpoint that consumes it
  • Violations are reported (with the offending mapping and the out-of-order positions) so you can fix them
  • An auto-fix is available that reorders endpoints to satisfy the dependencies while preserving your grouping as much as possible

How Order Is Calculated​

Automatic Calculation​

The system uses a dependency-respecting topological sort:

  1. Endpoints with no dependencies come first
  2. Dependent endpoints follow their sources
  3. Your preferred/manual order is honored where it doesn't break a dependency

Example​

Mappings:
  - Users endpoint provides user IDs
  - Posts endpoint needs user ID
  - Comments endpoint needs post ID

Calculated Order:
  1. List Users (no dependencies)
  2. Get User Posts (depends on Users)
  3. Get Post Comments (depends on Posts)

Reordering Endpoints​

Within Phases (Bulk tab)​

When phases exist, reorder by dragging endpoints between stages and dragging stages/phases in the Bulk tab. The phase-order validator flags any move that would break a dependency, and the auto-fix can repair it.

Manual Order (no phases)​

Without phases, the computed topological order is used. When you set a custom order, Traces stores it as a preferred order and re-derives a valid topological order from it, so dependencies are never violated.

Parameter Configuration Status​

Each endpoint's required path parameters are tracked (checkEndpointParameterConfiguration). An endpoint whose required path parameters aren't all configured (via a mapping, variable, or manual value) is considered skipped — it has nothing to fill the placeholder, so it can't run meaningfully. Configure the missing parameters to clear the skip.

Execution During Collection​

Sequence​

  1. The system computes the execution order (or uses the configured phases)
  2. Endpoints run in that order
  3. Extracted values are passed to dependent endpoints

Stages​

Endpoints grouped into the same stage have no dependency between them and form a logical batch — they don't need to run in a strict order relative to each other.

Failure Handling​

If an endpoint fails:

  • Dependent endpoints may be skipped (no source data)
  • Other independent branches continue
  • Errors are recorded for review

Best Practices​

Group by workflow — for example, all user-related endpoints in one phase before moving on to channels.

Dependencies First​

Ensure data sources run early:

  • List endpoints before detail endpoints
  • Parent resources before child resources

Validate Phases After Editing​

After reordering phases or stages, check for phase-order violations and apply the auto-fix if any appear.

Troubleshooting​

"Endpoint runs too early"​

  1. Check whether it should depend on another endpoint
  2. Add a mapping from the source endpoint
  3. The order adjusts automatically

"Can't place an endpoint where I want"​

  1. A dependency constraint is blocking it
  2. The phase-order validator will report the conflicting mapping
  3. Adjust the dependency or use auto-fix

"Endpoint shows as skipped"​

  1. It has unconfigured required path parameters
  2. Add a mapping, variable, or manual value for the missing parameter

"Circular dependency"​

Two endpoints depend on each other (A → B and B → A). Remove one dependency or restructure the data flow.