ArkRun

ArkRun is an immutable execution record for one ArkTeam pipeline trigger — step outputs, token usage, timestamps, and final result.

API: arkonis.dev/v1alpha1 Kind: ArkRun Short name: aorun Scope: Namespaced

ArkRun is an immutable record of one pipeline execution. Each time an ArkTeam pipeline is triggered — via ark trigger, an ArkEvent, or the dashboard — a new ArkRun is created automatically.

The ArkTeam defines what to run; the ArkRun records what happened: which steps ran, what each agent produced, how many tokens were consumed, and whether the run succeeded or failed.

What ArkRun contains

A snapshot of the ArkTeam spec at trigger time — stable even if the team is later updated.
The resolved input for this run (team defaults merged with trigger overrides).
Per-step execution state: phase, task ID, raw output, timestamps, token usage.
The final output once the pipeline succeeds.
Total token usage across all steps.

ArkRun.spec is written once and never mutated. spec.teamGeneration records which team spec was in effect.

Listing runs

# All runs in a namespace
kubectl get arkrun -n my-org

# Runs for a specific team
kubectl get arkrun -n my-org -l arkonis.dev/team=blog-pipeline

# NAME                           TEAM            PHASE       TOKENS   STARTED   AGE
# blog-pipeline-run-a1b2c3      blog-pipeline   Succeeded   6160     5m        5m
# blog-pipeline-run-d4e5f6      blog-pipeline   Failed      1204     1h        1h

Find the most recent run via the team status:

kubectl get arkteam blog-pipeline -n my-org \
  -o jsonpath='{.status.lastRunName}'

Inspecting a run

kubectl describe arkrun blog-pipeline-run-a1b2c3 -n my-org

Key fields in status:

status:
  phase: Succeeded
  startTime: "2026-03-17T10:00:00Z"
  completionTime: "2026-03-17T10:00:45Z"
  output: "Transformers use self-attention mechanisms to..."
  steps:
    - name: researcher
      phase: Succeeded
      taskID: "1710000001-0"
      output: "Research findings: ..."
      tokenUsage:
        inputTokens: 320
        outputTokens: 1240
        totalTokens: 1560
    - name: writer
      phase: Succeeded
      taskID: "1710000013-0"
      output: "Transformers use self-attention..."
      tokenUsage:
        inputTokens: 1240
        outputTokens: 3360
        totalTokens: 4600
  totalTokenUsage:
    inputTokens: 1560
    outputTokens: 4600
    totalTokens: 6160

Run phases

Phase	Meaning
`Pending`	Run created; waiting for the controller to start executing steps.
`Running`	One or more steps are in progress.
`Succeeded`	All steps completed. `status.output` is populated.
`Failed`	A step failed, budget was exceeded, or the run timed out.

Retrying

Use ark trigger to create a new run. The old run is preserved.

# Same input
ark trigger blog-pipeline -n my-org

# Different input
ark trigger blog-pipeline -n my-org --input '{"topic": "attention mechanisms"}'

To retry only the failed steps of an existing run (preserving succeeded steps):

ark retry blog-pipeline -n my-org

Spec reference

`spec`

spec is a snapshot written at trigger time and never mutated.

Field	Type	Description
`teamRef`	string	Name of the parent `ArkTeam`.
`teamGeneration`	int64	`ArkTeam.metadata.generation` at trigger time.
`input`	map[string]string	Resolved input: team `spec.input` defaults merged with per-trigger overrides.
`pipeline`	[]PipelineStep	Snapshot of `ArkTeam.spec.pipeline` at trigger time.
`roles`	[]RoleSpec	Snapshot of `ArkTeam.spec.roles` at trigger time.
`output`	string	Go template expression for the final result.
`timeoutSeconds`	int	Maximum wall-clock seconds. Zero means no timeout.
`maxTokens`	int64	Total token budget across all steps. Zero means no limit.

`status`

Field	Type	Description
`phase`	string	`Pending` \| `Running` \| `Succeeded` \| `Failed`
`steps`	[]StepStatus	Per-step execution state.
`output`	string	Resolved final output once `phase` is `Succeeded`.
`startTime`	Time	When the run began executing.
`completionTime`	Time	When the run reached a terminal phase.
`totalTokenUsage`	TokenUsage	Sum of token usage across all steps.
`observedGeneration`	int64	`.metadata.generation` this status reflects.
`conditions`	[]Condition	Standard conditions.

`status.steps[]`

Field	Type	Description
`name`	string	Role name matching `spec.pipeline[].role`.
`phase`	string	`Pending` \| `Running` \| `Succeeded` \| `Failed` \| `Skipped`
`taskID`	string	Redis Streams message ID. Use with `ark trace` to look up the OTel trace.
`output`	string	Raw text output from the agent.
`outputJSON`	string	Parsed JSON output when the step has `outputSchema`.
`startTime`	Time	When the step task was submitted to the queue.
`completionTime`	Time	When the step reached a terminal phase.
`message`	string	Human-readable detail for failures.
`iterations`	int	Number of loop iterations completed (for steps with `loop`).
`tokenUsage`	TokenUsage	Token usage for this step.

TokenUsage fields

Field	Type	Description
`inputTokens`	int64	Prompt tokens consumed.
`outputTokens`	int64	Completion tokens produced.
`totalTokens`	int64	`inputTokens + outputTokens`.

Printer columns

Column	JSONPath
`Team`	`.spec.teamRef`
`Phase`	`.status.phase`
`Tokens`	`.status.totalTokenUsage.totalTokens`
`Started`	`.status.startTime`

Run history and cleanup

Retention is controlled on the parent ArkTeam:

Team field	Default	Effect
`spec.successfulRunsHistoryLimit`	`10`	Keep last N successful runs.
`spec.failedRunsHistoryLimit`	`3`	Keep last N failed runs.
`spec.runRetainFor`	unset	Delete runs older than this duration.