---
title: "Start a run"
method: POST
path: "/api/v1/runs"
tags: ["Runs"]
---

# Start a run

`POST /api/v1/runs`

Start a run. Send JSON or multipart/form-data.

## Query parameters

- `version` string — Release or git ref. Defaults to latest.
- `wait_for_completion` integer — Seconds to wait before returning (max 600). Omit for async.

## Request body

- RunStartBody — Run envelope. Declare provenance with the `X-Eigenpal-Trigger` header (`api` or `cli`). Legacy 0.5.12 body shapes remain accepted.
  - `target` string, required — Automation target without a version suffix, e.g. workflows.invoice or agents.support.
  - `input` object — Scalar and structured automation arguments.
  - `files` object — File inputs as ingress references (`{ "$fileId": "file_..." }` or `{ "$inline": { filename, mimeType, base64 } }`). Upload bytes via multipart `files.<fieldName>` parts instead.
  - `overrides` object — Per-step output overrides. Workflow runs only.
    - `steps` object
  - `metadata` object — Caller-supplied run metadata.

## Response `200`

Run completed while waiting — same body as GET /api/v1/runs/:id

- union
  - RunAccepted
    - `id` string, required
    - `type` 'workflow' | 'agent', required
    - `finished` false, required
    - `source` RunSource
      - `id` string, required — Owning workflow id or agent id.
      - `name` string, nullable, required
      - `version` string, nullable, required — Workflow version label (workflow runs only).
      - `versionId` string, nullable — Captured workflow version id (workflow runs only).
      - `slug` string, nullable — Agent slug (agent runs only).
      - `model` string, nullable — LLM model used (agent runs only).
      - `git` RunSourceGit
        - `requestedRef` string, nullable, required
        - `resolvedRef` string, nullable, required
        - `resolvedTag` string, nullable, required
        - `commitSha` string, nullable, required
      - `implementationAvailable` boolean — Whether the live workflow/agent implementation still exists (`GET /api/v1/runs/:id` detail only).
      - `automationFound` boolean — Whether the owning automation registry row still exists (`GET /api/v1/runs/:id` detail only).
      - `currentVersion` string, nullable — Current released workflow version label when the source is live (`GET /api/v1/runs/:id` detail only).
  - Run
    - `id` string, required
    - `type` 'workflow' | 'agent', required
    - `finished` boolean, required — True when the run has reached a terminal status.
    - `sampleRank` number, required — Deterministic pseudo-random rank in [0, 1) for this run within the tenant. Use with a sample rate threshold to review a stable subset.
    - `timing` RunTiming, required
      - `createdAt` string, required
      - `startedAt` string, nullable, required
      - `completedAt` string, nullable, required
      - `durationMs` number, nullable, required
      - `cancelRequestedAt` string, nullable, required — When the user requested cancel; status may still be `running` until the worker stops.
    - `source` RunSource, required
      - `id` string, required — Owning workflow id or agent id.
      - `name` string, nullable, required
      - `version` string, nullable, required — Workflow version label (workflow runs only).
      - `versionId` string, nullable — Captured workflow version id (workflow runs only).
      - `slug` string, nullable — Agent slug (agent runs only).
      - `model` string, nullable — LLM model used (agent runs only).
      - `git` RunSourceGit
        - `requestedRef` string, nullable, required
        - `resolvedRef` string, nullable, required
        - `resolvedTag` string, nullable, required
        - `commitSha` string, nullable, required
      - `implementationAvailable` boolean — Whether the live workflow/agent implementation still exists (`GET /api/v1/runs/:id` detail only).
      - `automationFound` boolean — Whether the owning automation registry row still exists (`GET /api/v1/runs/:id` detail only).
      - `currentVersion` string, nullable — Current released workflow version label when the source is live (`GET /api/v1/runs/:id` detail only).
    - `trigger` RunTrigger, required
      - `type` string, nullable, required
      - `by` object, nullable, required
        - `id` string, required
        - `name` string, nullable, required
        - `email` string, required
      - `email` unknown
    - `eval` RunEval
      - `example` string, nullable, required — Eval example label (agent example name or workflow example id).
      - `exampleId` string, nullable — Workflow eval example folder id (workflow runs only).
      - `score` number, nullable, required
      - `passed` boolean, nullable, required
    - `output` object, nullable — Completed runs only.
    - `files` RunArtifact[] — Completed runs only. Download with GET /api/v1/runs/:id/artifacts/:path.
      - `name` string, required
      - `role` string, required — `input`, `output`, `debug`, `report`, or another stable artifact role.
      - `path` string, required — Canonical artifact path for GET /api/v1/runs/:id/artifacts/:path.
      - `stepName` string — Workflow step that produced the file, when known.
      - `contentType` string, nullable
      - `size` integer, nullable
    - `error` string, nullable
    - `input` RunInput
      - `args` unknown, required
      - `files` RunFile[] — Uploaded input files (agent runs only).
        - `name` string, required
      - `metadata` unknown
    - `usage` RunUsage
      - `tokens` object, required
        - `input` number, nullable, required
        - `output` number, nullable, required
        - `cacheRead` number, nullable, required
        - `cacheWrite` number, nullable, required
      - `creditsCharged` number, nullable, required
      - `durationMs` number, nullable, required
      - `llmCallCount` number — LLM call count (workflow runs only).
      - `ocrPagesProcessed` number — OCR pages processed (workflow runs only).
      - `agentTurns` number, nullable — Agent conversation turns (agent runs only).
    - `execution` union, required — Slim execution metadata always present. Pass `expand=execution` to replace with full RunExecution (WorkflowRunExecution or AgentRunExecution depending on run type).
      - RunExecutionMeta
        - `status` 'created' | 'pending' | 'running' | 'waiting' | 'finalizing' | 'completed' | 'failed' | 'cancelled' | 'rejected', required
        - `schemaValid` boolean, nullable, required — Whether the completed output matched the workflow or agent output schema.
        - `batchId` string, nullable, required — Experiment batch id when the run is part of a batch.
        - `retry` RunExecutionRetry, required
          - `number` number, required — Retry attempt index (0 = original run).
          - `previousRunId` string, nullable, required — Run id of the prior attempt in the retry chain.
          - `nextRun` object, nullable, required — Retry run spawned from this run, if any.
            - `id` string, required
            - `status` string, required
        - `review` RunReviewSummary
          - `verdict` 'correct' | 'incorrect', nullable, required
          - `status` 'open' | 'closed' | 'wont_fix', required
          - `hasNote` boolean, required — True when review notes were left.
          - `correctionCount` integer, required — Number of field/file corrections.
      - union
        - WorkflowRunExecution
          - `status` 'created' | 'pending' | 'running' | 'waiting' | 'finalizing' | 'completed' | 'failed' | 'cancelled' | 'rejected', required
          - `schemaValid` boolean, nullable, required — Whether the completed output matched the workflow or agent output schema.
          - `batchId` string, nullable, required — Experiment batch id when the run is part of a batch.
          - `retry` RunExecutionRetry, required
            - `number` number, required — Retry attempt index (0 = original run).
            - `previousRunId` string, nullable, required — Run id of the prior attempt in the retry chain.
            - `nextRun` object, nullable, required — Retry run spawned from this run, if any.
              - …
          - `review` RunReview
            - `id` string, required
            - `verdict` 'correct' | 'incorrect', nullable, required
            - `status` 'open' | 'closed' | 'wont_fix', required
            - `note` string, required
            - `correctedOutput` unknown
            - `reviewedBy` string, nullable, required — User id of the last reviewer. Read-only; set from the authenticated user or API key creator.
            - `reviewedByEmail` string, nullable, required — Email of the last reviewer. Read-only; set from the authenticated user or API key creator.
            - `reviewedAt` string, required
            - `closedBy` string, nullable, required — User id recorded when the review was closed. Read-only; set when status becomes closed or wont_fix.
            - `closedByEmail` string, nullable, required — Email recorded when the review was closed. Read-only; set when status becomes closed or wont_fix.
            - `closedAt` string, nullable, required
            - `closedNote` string, nullable, required
            - `createdAt` string, required
            - `updatedAt` string, required
            - `corrections` RunReviewCorrection[], required
              - …
          - `steps` unknown[], required — Per-step executions of the workflow run.
            - unknown
          - `definitionSnapshot` unknown
          - `expected` object — Ground-truth expected output and files.
            - `output` unknown
            - `files` RunFile[]
              - …
        - AgentRunExecution
          - `status` 'created' | 'pending' | 'running' | 'waiting' | 'finalizing' | 'completed' | 'failed' | 'cancelled' | 'rejected', required
          - `schemaValid` boolean, nullable, required — Whether the completed output matched the workflow or agent output schema.
          - `batchId` string, nullable, required — Experiment batch id when the run is part of a batch.
          - `retry` RunExecutionRetry, required
            - `number` number, required — Retry attempt index (0 = original run).
            - `previousRunId` string, nullable, required — Run id of the prior attempt in the retry chain.
            - `nextRun` object, nullable, required — Retry run spawned from this run, if any.
              - …
          - `review` RunReview
            - `id` string, required
            - `verdict` 'correct' | 'incorrect', nullable, required
            - `status` 'open' | 'closed' | 'wont_fix', required
            - `note` string, required
            - `correctedOutput` unknown
            - `reviewedBy` string, nullable, required — User id of the last reviewer. Read-only; set from the authenticated user or API key creator.
            - `reviewedByEmail` string, nullable, required — Email of the last reviewer. Read-only; set from the authenticated user or API key creator.
            - `reviewedAt` string, required
            - `closedBy` string, nullable, required — User id recorded when the review was closed. Read-only; set when status becomes closed or wont_fix.
            - `closedByEmail` string, nullable, required — Email recorded when the review was closed. Read-only; set when status becomes closed or wont_fix.
            - `closedAt` string, nullable, required
            - `closedNote` string, nullable, required
            - `createdAt` string, required
            - `updatedAt` string, required
            - `corrections` RunReviewCorrection[], required
              - …
          - `files` object, required
            - `output` RunFile[], required — Output artifacts the agent produced.
              - …
          - `expected` object — Ground-truth expected output and files.
            - `output` unknown
            - `files` RunFile[]
              - …
          - `comparison` unknown
    - `debug` RunDebug
      - `observability` unknown, required
      - `traceId` string, nullable — Workflow trace id for span lookup (workflow runs only).

## Other responses

- `201` — Run accepted (async)
- `202` — Wait expired with a non-terminal status — poll GET /api/v1/runs/:id
- `400` — Validation error. Request shape did not match the spec.
- `401` — Missing or invalid API key
- `403` — Trigger disabled or insufficient scope. Run start may return api_trigger_disabled when the API trigger is off, or manual_trigger_disabled for dashboard runs on API-only workflows.
- `404` — Resource not found
- `413` — Payload too large. Upload exceeded the per-request size cap.
- `429` — Rate limit exceeded
- `500` — Internal server error

---

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