Skip to main content
POST
/
v1
/
workflows
/
evals
/
runs
from retab import Retab

client = Retab()

run = client.workflows.evals.runs.create(
    workflow_id="wf_abc123xyz",
    scope={
        "type": "single",
        "eval_id": "wfnodeeval_hsLEQiM61ez9Piv147MWk",
    },
)

print(run.id, run.lifecycle.status)

{
  "id": "wfevalrun_q1z2",
  "workflow_id": "wf_abc123xyz",
  "workflow_version_id": "draft_2026_05_18",
  "trigger": { "type": "api" },
  "lifecycle": { "status": "pending" },
  "timing": {
    "created_at": "2026-05-18T10:00:00Z",
    "started_at": null,
    "completed_at": null,
    "duration_ms": null
  },
  "eval_id": "wfnodeeval_hsLEQiM61ez9Piv147MWk",
  "target": { "type": "block", "block_id": "block_extract_invoice" },
  "total_evals": 1,
  "counts": {
    "lifecycle_counts": {
      "pending": 1,
      "queued": 0,
      "running": 0,
      "completed": 0,
      "error": 0,
      "cancelled": 0
    },
    "outcome": {
      "passed": 0,
      "failed": 0,
      "blocked": 0
    }
  }
}
Create a workflow-eval run against the current workflow draft. A run can execute one saved eval, every eval for one block, or every eval in the workflow. The canonical route is flat: send workflow_id in the request body and optionally narrow execution with scope. If scope is omitted, every saved eval in the workflow runs. The response is a run resource. Use its id with the run-id-first endpoints: Get Workflow Eval Run, List Eval Run Results. The request body has a workflow context and an optional scope:
  • omitted scope - run every saved eval in the workflow.
  • scope.type = "single" - run one saved eval by eval_id.
  • scope.type = "block" - run every saved eval for one block by block_id.
from retab import Retab

client = Retab()

run = client.workflows.evals.runs.create(
    workflow_id="wf_abc123xyz",
    scope={
        "type": "single",
        "eval_id": "wfnodeeval_hsLEQiM61ez9Piv147MWk",
    },
)

print(run.id, run.lifecycle.status)

{
  "id": "wfevalrun_q1z2",
  "workflow_id": "wf_abc123xyz",
  "workflow_version_id": "draft_2026_05_18",
  "trigger": { "type": "api" },
  "lifecycle": { "status": "pending" },
  "timing": {
    "created_at": "2026-05-18T10:00:00Z",
    "started_at": null,
    "completed_at": null,
    "duration_ms": null
  },
  "eval_id": "wfnodeeval_hsLEQiM61ez9Piv147MWk",
  "target": { "type": "block", "block_id": "block_extract_invoice" },
  "total_evals": 1,
  "counts": {
    "lifecycle_counts": {
      "pending": 1,
      "queued": 0,
      "running": 0,
      "completed": 0,
      "error": 0,
      "cancelled": 0
    },
    "outcome": {
      "passed": 0,
      "failed": 0,
      "blocked": 0
    }
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Create a workflow eval run. Provide a workflow_id, and optionally narrow execution with scope to a single eval or one block. Omit scope to run every saved workflow eval.

​
workflow_id
string
required
​
scope
WorkflowEvalRunSingleScope · object

Run one saved workflow eval in the workflow.

Response

Successful Response

A batch execution of a workflow's evals, with overall lifecycle, timing, and pass/fail counts.

​
id
string
required
​
workflow_id
string
required
​
workflow_version_id
string
required
​
trigger
EvalRunTrigger · object
required
​
lifecycle
PendingWorkflowEvalRun · object
required

The eval run has been created but execution has not started.

​
timing
WorkflowEvalRunTiming · object
required
​
total_evals
integer
required
​
target
EvalRunBlockTarget · object

Public workflow-eval target.

The storage layer remains block-scoped today, but the API shape names the tested entity explicitly so workflow-level targets can be added later.

​
eval_id
string | null
​
counts
BlockEvalBatchExecutionCounts · object

Aggregate counts for a batch of block-eval runs.

Each individual run contributes to exactly one lifecycle_counts bucket, and additionally to one outcome bucket when lifecycle_counts.completed is incremented.

​
freshness
EvalRunFreshness · object