Runs

A run is one execution of a network. It records the input, the status and output of every node, the models chosen, energy and token metrics, an evaluation summary, and a tamper-evident ledger. Runs are immutable history: you start one by executing a network or rendering a template, then read it back here.

Follow a run by polling Retrieve a run: the run record carries the overall status and each node's status and output, updated as the run proceeds. The other endpoints cover history and review: list and retrieve runs, read node outputs and artifacts, resolve approval gates, leave feedback, and read the run's proof and related runs.

Every endpoint on this page requires an access token. Send it as a bearer token, or rely on the session cookie forwarded by the same-origin /networks-api proxy.

The run object

One execution of a network.

Attributes

run_id string

Identifier of the form run-<UTC timestamp>-<random>, for example run-20260901-093000-a1b2c3.
network_id string

The network that was run.
network_version string

The version of the network that was run.
domain_id string

Domain the run executed under.
triggered_by string

What started the run. Anything unrecognised is recorded as user.
Possible values
- user
- trigger:email
- trigger:teams
status string

Overall run status. partial means some nodes degraded but useful output remains.
Possible values
- started
- completed
- partial
- failed
error nullable string

Failure summary when the run did not complete cleanly.
started_at string

Start time, ISO 8601 with an explicit offset.
completed_at nullable string

Completion time, ISO 8601, or null while running.
input object

The input payload the run was started with.
metrics object

Aggregate run metrics.
Show child attributes Hide child attributes
- total_tokens nullable integer
  
  Total provider tokens across nodes.
- total_duration_ms nullable number
  
  Wall-clock duration in milliseconds.
- total_watts_estimated nullable number
  
  Estimated energy draw.
- models_used array of strings
  
  Distinct model ids used in the run.
evaluation object

Evaluation summary for the run.
Show child attributes Hide child attributes
- enabled boolean
  
  Whether evaluation was enabled.
- overall_score nullable number
  
  Overall score in 0–1.
- pass_threshold nullable number
  
  Threshold the score is compared against.
- passed nullable boolean
  
  Whether the run passed.
- node_scores object
  
  Per-node scores keyed by node id.
nodes object

Per-node records keyed by node id. Large text fields are truncated here; fetch the full output with Retrieve a node output.
Show child attributes Hide child attributes
- node_id string
  
  The node's id.
- label nullable string
  
  Display label.
- node_type nullable string
  
  The node's type.
- status string
  
  Node status.
  Possible values
  - started
  - completed
  - failed
  - partial
  - skipped
  - awaiting_approval
- model_used nullable string
  
  Model that produced the output, for LLM-backed nodes.
- tokens_in nullable integer
  
  Prompt tokens.
- tokens_out nullable integer
  
  Completion tokens.
- duration_ms nullable number
  
  Node duration in milliseconds.
- output nullable object
  
  The node's result payload (truncated in this view).
- error nullable string
  
  Error message when the node failed.
memory_graph_status string

Whether the run has been indexed into the memory graph for related-run and hint lookups.
Possible values
- pending
- ready
- disabled
feedback nullable object

Feedback submitted for the run, or null. See Retrieve run feedback.
pending_approvals array of objects

Approval gates currently waiting, each flagged actionable when a decision can still be recorded.
multi_agent_summary nullable object

An additive, per-node card summary for rendering the run. Carries a version, a cards array, and a summary with node counts.
Show child attributes Hide child attributes
- version string
  
  Schema version of the summary payload.
- cards array of objects
  
  One card per node with its role, model, body, and status.
- summary object
  
  Totals: total_nodes, completed, failed, skipped, and models_used.

The run object

{
  "run_id": "run-20260901-093000-a1b2c3",
  "network_id": "support-triage",
  "network_version": "1.2",
  "domain_id": "customer-success",
  "triggered_by": "user",
  "status": "completed",
  "error": null,
  "started_at": "2026-09-01T09:30:00Z",
  "completed_at": "2026-09-01T09:30:12Z",
  "input": {
    "task": "Classify ticket 4471 and draft a reply."
  },
  "metrics": {
    "total_tokens": 1840,
    "total_duration_ms": 11840,
    "total_watts_estimated": 2.1,
    "models_used": [
      "llama-3.3-70b-instruct"
    ]
  },
  "evaluation": {
    "enabled": true,
    "overall_score": 0.82,
    "pass_threshold": 0.75,
    "passed": true,
    "node_scores": {
      "draft_reply": 0.82
    }
  },
  "nodes": {
    "classify": {
      "node_id": "classify",
      "label": "Classify the ticket",
      "node_type": "LLMAgent",
      "status": "completed",
      "model_used": "llama-3.3-70b-instruct",
      "tokens_in": 320,
      "tokens_out": 40,
      "duration_ms": 2100,
      "output": {
        "model_id": "llama-3.3-70b-instruct",
        "text": "Category: billing"
      },
      "error": null
    },
    "draft_reply": {
      "node_id": "draft_reply",
      "label": "Draft a reply",
      "node_type": "LLMAgent",
      "status": "completed",
      "model_used": "llama-3.3-70b-instruct",
      "tokens_in": 1200,
      "tokens_out": 280,
      "duration_ms": 9740,
      "output": {
        "model_id": "llama-3.3-70b-instruct",
        "text": "Hello, thanks for reaching out..."
      },
      "error": null
    }
  },
  "memory_graph_status": "ready",
  "feedback": null,
  "pending_approvals": [],
  "multi_agent_summary": {
    "version": "v1",
    "cards": [
      {
        "node_id": "draft_reply",
        "label": "Draft a reply",
        "node_type": "LLMAgent",
        "role": "agent",
        "model_id": "llama-3.3-70b-instruct",
        "body_format": "text",
        "status": "completed",
        "score": 0.82
      }
    ],
    "summary": {
      "total_nodes": 2,
      "completed": 2,
      "failed": 0,
      "skipped": 0,
      "models_used": [
        "llama-3.3-70b-instruct"
      ]
    }
  }
}

List runs

GET /networks-api/runs

Returns run summaries, newest first.

Returns a page of lightweight run summaries for execution-history views. Node outputs are omitted by default; set include_nodes=true to include per-node records.

Filter by network_id, domain_id, status, and a started_after/started_before window. Page with limit and offset. Set include_total=false to stop scanning once the requested slice is collected, in which case total is returned as -1.

Authentication: Bearer token How it works

Query parameters

network_id string

Only runs of this network.
domain_id string

Only runs in this domain.
status string

Only runs with this status.
Possible values
- started
- completed
- partial
- failed
started_after string

Only runs started at or after this ISO 8601 time.
started_before string

Only runs started at or before this ISO 8601 time.
limit integer

Maximum runs to return. 0 returns all matching runs.

Defaults to 50.
offset integer

Number of matching runs to skip.

Defaults to 0.
include_nodes boolean

Include per-node records in each summary.

Defaults to false.
include_total boolean

Compute the total match count. When false, total is -1.

Defaults to true.

Returns

Returns a page of run summaries with the total count and the window.

Request

curl "$VDF_BASE_URL/networks-api/runs?network_id=support-triage&limit=2" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"

Response 200

{
  "runs": [
    {
      "run_id": "run-20260901-093000-a1b2c3",
      "network_id": "support-triage",
      "network_name": "Support triage",
      "network_version": "1.2",
      "domain_id": "customer-success",
      "status": "completed",
      "started_at": "2026-09-01T09:30:00Z",
      "completed_at": "2026-09-01T09:30:12Z",
      "error": null,
      "input_preview": "Classify ticket 4471 and draft a reply.",
      "memory_graph_status": "ready"
    }
  ],
  "total": 1,
  "limit": 2,
  "offset": 0
}

Retrieve a run

GET /networks-api/runs/{run_id}

Retrieves a full run record.

Returns the run object, including per-node records and the multi_agent_summary. Pass view=monitoring to skip the summary computation for a lighter payload while a run is in progress.

Authentication: Bearer token How it works

Path parameters

run_id string Required

The run's identifier.

Query parameters

view string

monitoring omits multi_agent_summary for a lighter payload.

Defaults to full.
Possible values
- full
- monitoring

Returns

Returns the run object.

Errors

404 No run with this identifier exists.

Request

curl "$VDF_BASE_URL/networks-api/runs/run-20260901-093000-a1b2c3" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"

Response 200

{
  "run_id": "run-20260901-093000-a1b2c3",
  "network_id": "support-triage",
  "network_version": "1.2",
  "domain_id": "customer-success",
  "status": "completed",
  "started_at": "2026-09-01T09:30:00Z",
  "completed_at": "2026-09-01T09:30:12Z",
  "input": {
    "task": "Classify ticket 4471 and draft a reply."
  },
  "metrics": {
    "total_tokens": 1840,
    "total_duration_ms": 11840,
    "models_used": [
      "llama-3.3-70b-instruct"
    ]
  },
  "evaluation": {
    "enabled": true,
    "overall_score": 0.82,
    "pass_threshold": 0.75,
    "passed": true,
    "node_scores": {
      "draft_reply": 0.82
    }
  },
  "nodes": {
    "draft_reply": {
      "node_id": "draft_reply",
      "node_type": "LLMAgent",
      "status": "completed",
      "model_used": "llama-3.3-70b-instruct",
      "output": {
        "model_id": "llama-3.3-70b-instruct",
        "text": "Hello, thanks for reaching out..."
      }
    }
  },
  "memory_graph_status": "ready",
  "feedback": null,
  "pending_approvals": []
}

Retrieve a node output

GET /networks-api/runs/{run_id}/nodes/{node_id}

Returns one node's full output payload.

Returns the full, untruncated output payload for a single node. The shape depends on the node type: LLM nodes return { "model_id", "text" }; tool nodes return { "tool_id", "ok", "result", "error" }.

Authentication: Bearer token How it works

Path parameters

run_id string Required

The run's identifier.
node_id string Required

The node's identifier.

Returns

Returns the node's output payload.

Errors

404 No output exists for this node.

Request

curl "$VDF_BASE_URL/networks-api/runs/run-20260901-093000-a1b2c3/nodes/draft_reply" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"

Response 200

{
  "model_id": "llama-3.3-70b-instruct",
  "text": "Hello, thanks for reaching out..."
}

List run artifacts

GET /networks-api/runs/{run_id}/artifacts

Returns the files a run produced.

Returns the artifacts written during the run, each with a relative path and size_bytes.

Authentication: Bearer token How it works

Path parameters

run_id string Required

The run's identifier.

Returns

Returns the run's artifact list.

Errors

404 The run does not exist.

Request

curl "$VDF_BASE_URL/networks-api/runs/run-20260901-093000-a1b2c3/artifacts" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"

Response 200

{
  "run_id": "run-20260901-093000-a1b2c3",
  "artifacts": [
    {
      "path": "artifacts/reply.md",
      "size_bytes": 1842
    }
  ]
}

Retrieve run feedback

GET /networks-api/runs/{run_id}/feedback

Returns the feedback recorded for the run, or null if none has been submitted.

Authentication: Bearer token How it works

Path parameters

run_id string Required

The run's identifier.

Returns

Returns the run's feedback, or null.

Errors

404 The run does not exist.

Request

curl "$VDF_BASE_URL/networks-api/runs/run-20260901-093000-a1b2c3/feedback" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"

Response 200

{
  "run_id": "run-20260901-093000-a1b2c3",
  "feedback": {
    "sentiment": "like",
    "comment": "Accurate classification.",
    "submitted_at": "2026-09-01T10:00:00Z",
    "submitted_by_user_id": 42,
    "source": "portal_agents_chat"
  }
}

Submit run feedback

POST /networks-api/runs/{run_id}/feedback

Records like/dislike feedback for a run.

Records a single piece of feedback for the run and feeds the signal into routing and tool-selection learning. Feedback can be submitted once per run.

sentiment must be like or dislike. source must be portal_agents_chat. Comments are trimmed to 2000 characters. The response echoes the stored feedback and how many learning decisions were updated.

Authentication: Bearer token How it works

Path parameters

run_id string Required

The run's identifier.

Body parameters application/json

sentiment string Required

The feedback signal.
Possible values
- like
- dislike
comment string

Optional free-text comment, trimmed to 2000 characters.
source string

Where the feedback originated.

Defaults to portal_agents_chat.
Possible values
- portal_agents_chat
message_id string

Client message id the feedback relates to.
execution_id string

Client execution id the feedback relates to.

Returns

Returns the stored feedback and a count of learning updates by kind.

Errors

404 The run does not exist.
409 Feedback has already been submitted for this run.

Request

curl -X POST "$VDF_BASE_URL/networks-api/runs/run-20260901-093000-a1b2c3/feedback" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sentiment": "like",
    "comment": "Accurate classification."
  }'

Response 200

{
  "run_id": "run-20260901-093000-a1b2c3",
  "feedback": {
    "sentiment": "like",
    "comment": "Accurate classification.",
    "submitted_at": "2026-09-01T10:00:00Z",
    "submitted_by_user_id": 42,
    "source": "portal_agents_chat"
  },
  "learning_updates": {
    "model_routing": 2,
    "tool_selection": 0,
    "tool_backend_routing": 0,
    "plan_rewrite": 0
  }
}

List run approvals

GET /networks-api/runs/{run_id}/approvals

Returns every approval gate the run has opened, pending or decided, along with a pending subset. Each gate carries the rules that matched, an is_open flag, and an actionable flag that is true only when a decision can still be recorded.

Authentication: Bearer token How it works

Path parameters

run_id string Required

The run's identifier.

Returns

Returns the run's approval gates and the pending subset.

Errors

404 The run does not exist.

Request

curl "$VDF_BASE_URL/networks-api/runs/run-20260901-093000-a1b2c3/approvals" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"

Response 200

{
  "run_id": "run-20260901-093000-a1b2c3",
  "approvals": [
    {
      "request_id": "apr-1",
      "run_id": "run-20260901-093000-a1b2c3",
      "node_id": "approve_send",
      "node_label": "Approve before sending",
      "status": "pending",
      "message": "Review the drafted reply before it is sent.",
      "matched_rules": [
        {
          "rule_id": "always",
          "kind": "always"
        }
      ],
      "requested_at": "2026-09-01T09:30:05Z",
      "expires_at": "2026-09-01T09:45:05Z",
      "is_open": true,
      "actionable": true
    }
  ],
  "pending": [
    {
      "request_id": "apr-1",
      "node_id": "approve_send",
      "status": "pending",
      "is_open": true,
      "actionable": true
    }
  ]
}

Decide a run approval

POST /networks-api/runs/{run_id}/approvals/{node_id}

Approves or rejects a waiting approval gate.

Records a decision on a waiting approval gate so the run can continue. decision must be approve or reject; an optional comment is trimmed to 2000 characters. A rejected gate follows the node's on-reject behaviour (halt, warn, or branch).

An approval node can be configured so that only an administrator may decide its gate; such a gate rejects any other caller.

Authentication: Bearer token How it works

Path parameters

run_id string Required

The run's identifier.
node_id string Required

The approval node to decide.

Body parameters application/json

decision string Required

The decision to record.
Possible values
- approve
- reject
comment string

Optional reviewer comment, trimmed to 2000 characters.

Returns

Returns the recorded decision.

Errors

403 The caller may not resolve this approval gate.
404 The run or the approval request does not exist.
409 The gate is already resolved, or the run is no longer waiting for approval.

Request

curl -X POST "$VDF_BASE_URL/networks-api/runs/run-20260901-093000-a1b2c3/approvals/approve_send" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approve",
    "comment": "Reply looks good."
  }'

Response 200

{
  "run_id": "run-20260901-093000-a1b2c3",
  "node_id": "approve_send",
  "decision": "approve",
  "status": "accepted"
}

List run hints

GET /networks-api/runs/{run_id}/hints

Returns suggested improvements for a run.

Returns structured hints derived from the run and its most similar past runs — for example pinning a node to a model that scored better on a highly similar run, or surfacing feedback-loop text. Apply selected hints with Apply run hints.

Authentication: Bearer token How it works

Path parameters

run_id string Required

The run's identifier.

Returns

Returns the hints for the run and their count.

Errors

404 The run does not exist.

Request

curl "$VDF_BASE_URL/networks-api/runs/run-20260901-093000-a1b2c3/hints" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"

Response 200

{
  "run_id": "run-20260901-093000-a1b2c3",
  "count": 1,
  "hints": [
    {
      "hint_id": "pin_model:run-20260901-093000-a1b2c3:run-20260830-084500-9f0e11:draft_reply:llama-3.3-70b-instruct",
      "type": "pin_model",
      "title": "Pin model for `draft_reply`",
      "message": "A highly similar past run achieved higher proof. Consider pinning `draft_reply` to `llama-3.3-70b-instruct`.",
      "confidence": 0.72,
      "target": {
        "node_id": "draft_reply"
      },
      "proposed": {
        "strategy": "pinned",
        "pinned_model": "llama-3.3-70b-instruct"
      }
    }
  ]
}

Apply run hints

POST /networks-api/runs/{run_id}/apply_hints

Applies selected hints to produce a revised network.

Applies selected hints. By default (mode: new_network) a derived network is saved at version 1.0 with the changes applied, leaving the original untouched; mode: bump_version writes the changes back onto the original network with the requested bump. Omit hint_ids to apply every available hint. Only pin_model hints change the spec; others are reported as rejected.

Authentication: Bearer token How it works

Path parameters

run_id string Required

The run's identifier.

Body parameters application/json

hint_ids array of strings

Hint ids to apply. Omit to apply all available hints.
mode string

Save the result as a new derived network or as a new version of the original.

Defaults to new_network.
Possible values
- new_network
- bump_version
bump string

Version increment used when mode is bump_version.

Defaults to minor.
Possible values
- none
- minor
- major

Returns

Returns which hints were applied or rejected and the resulting network specification.

Errors

404 The run or its base network does not exist.

Request

curl -X POST "$VDF_BASE_URL/networks-api/runs/run-20260901-093000-a1b2c3/apply_hints" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hint_ids": [
      "pin_model:run-20260901-093000-a1b2c3:run-20260830-084500-9f0e11:draft_reply:llama-3.3-70b-instruct"
    ],
    "mode": "new_network"
  }'

Response 200

{
  "status": "ok",
  "base_network_id": "support-triage",
  "base_network_version": "1.2",
  "derived_network_id": "support-triage-derived-20260901-100500",
  "derived_network_version": "1.0",
  "applied": [
    "pin_model:run-20260901-093000-a1b2c3:run-20260830-084500-9f0e11:draft_reply:llama-3.3-70b-instruct"
  ],
  "rejected": [],
  "warnings": []
}

Retrieve run proof

GET /networks-api/runs/{run_id}/proof

Returns a composite proof score for the run combining evaluation quality, energy efficiency, and replay evidence, together with its provenance (the run's tamper-evident ledger hash and parent hash), cluster label, and any insights.

Proof is computed after the run is indexed into the memory graph. While that is still pending the response has status: pending and null proof fields.

Authentication: Bearer token How it works

Path parameters

run_id string Required

The run's identifier.

Returns

Returns the run's proof score, components, provenance, cluster, and insights.

Request

curl "$VDF_BASE_URL/networks-api/runs/run-20260901-093000-a1b2c3/proof" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"

Response 200

{
  "run_id": "run-20260901-093000-a1b2c3",
  "proof_score": 0.78,
  "proof_components": {
    "eval_norm": 0.82,
    "energy_eff_norm": 0.6,
    "determinism_score": 0.9,
    "weights": {
      "eval": 0.4,
      "energy": 0.3,
      "determinism": 0.3
    }
  },
  "provenance": {
    "ledger_sha256": "6f1e...c2",
    "parent_run_hash": "9a3d...44",
    "entry_count": 4
  },
  "cluster": {
    "cluster_id": "support-triage:run-20260830-084500-9f0e11",
    "attach_threshold": 0.86,
    "strong_neighbors": [
      "run-20260830-084500-9f0e11"
    ]
  },
  "insights": []
}

GET /networks-api/runs/{run_id}/related

Returns runs most similar to a given run.

Returns the runs most similar to this one by specification embedding, each with a similarity score. Similarity is available only once the run has been indexed into the memory graph; until then the response reports the current status and an empty list.

Authentication: Bearer token How it works

Path parameters

run_id string Required

The run's identifier.

Query parameters

top_k integer

Maximum number of related runs to return.

Defaults to 10.

Returns

Returns the memory-graph status and the related runs with similarity scores.

Request

curl "$VDF_BASE_URL/networks-api/runs/run-20260901-093000-a1b2c3/related?top_k=5" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"

Response 200

{
  "status": "ready",
  "related_runs": [
    {
      "run_id": "run-20260830-084500-9f0e11",
      "similarity": 0.91
    }
  ]
}

Runs

Attributes

Query parameters

Returns

Path parameters

Query parameters

Returns

Errors

Path parameters

Returns

Errors

Path parameters

Returns

Errors

Path parameters

Returns

Errors

Path parameters

Body parameters application/json

Returns

Errors

Path parameters

Returns

Errors

Path parameters

Body parameters application/json

Returns

Errors

Path parameters

Returns

Errors

Path parameters

Body parameters application/json

Returns

Errors

Path parameters

Returns

Path parameters

Query parameters

Returns

Request a Demo

Thank You!