Runs

Description and operation

General

A run is one execution of one version of a pipeline. A start by hand uses the newest version, or the version that you name. Each run records what it used, so you can see later what ran and why.

A run keeps the definition that it started with. A later save does not change a run that exists. The full run document is in the pipelines API.

To do these tasks with an AI agent, see Agentic workflows – General.

Start options

The raw API has no clone key. It takes environment as a name, or as {"clone": "name"}. The SDKs and --clone build the second form.

The start call plans the run at once and answers 202 with the run in queued. If the version cannot run, the call answers 422 with one line for each problem, and records nothing. For environments, see Secrets, registries and environments.

Logs

Each job has one log that holds its output and its error output. The log shows ▶ and the step name before each step, and a last line ■ with the cause when the job did not succeed. You read a log from a byte offset, so a program follows a running job by reading again from next. One answer holds at most 1 MiB. The SDK methods logs and follow do this for you.

A log stops at 8 MiB with the line [log truncated: past 8 MiB]. Secret values in a log show as ***. See Masking.

Cancel

A cancel of a queued run ends it at once. A cancel of a running run sets cancelRequested. The platform then stops each running job and cancels the pending jobs. A cancel of a finished run answers 409.

Retention

The platform deletes a run record 90 days after the run ends. A job log is deleted 90 days after the run started. After that, a read of the log returns the single line log expired: job logs are kept for 90 days.

Tasks

Start a run of a pinned version

Reason for the task: Run a known version of a pipeline, with the inputs and the environment that you choose.

Job set-up

• Access: you. For a team, an active member.
• Conditions: the pipeline refresh has version 2. See Show the versions of a pipeline.
• References: POST /v1/pipelines/{owner}/{pipeline}/runs, SDK pipelines.run.

Procedure

1. Start the run. Leave out version to run the newest version.

   PythonCopy

   run = kl.pipelines.run(owner="acme", pipeline="refresh", version=2, inputs={"day": "2026-10-21"})print(run.id, run.pipeline_version, run.state)

   TypeScriptCopy

   const run = await kl.pipelines.run({ owner: "acme", pipeline: "refresh", version: 2, inputs: { day: "2026-10-21" } });console.log(run.id, run.doc.pipelineVersion, run.state);

   GoCopy

   run, err := kl.Pipelines.Run(kloudlite.RunPipeline{    Owner: "acme", Pipeline: "refresh", Version: 2,    Inputs: map[string]string{"day": "2026-10-21"},})if err != nil {    log.Fatal(err)}fmt.Println(run.ID, run.PipelineVersion, run.State)

   RubyCopy

   run = kl.pipelines.run(owner: "acme", pipeline: "refresh", version: 2, inputs: { "day" => "2026-10-21" })puts run.id, run.pipeline_version, run.state

   JavaCopy

   var run = kl.pipelines().run(new Kloudlite.RunPipeline().owner("acme").pipeline("refresh").version(2).input("day", "2026-10-21"));System.out.println(run.id() + " " + run.pipelineVersion() + " " + run.state());

   CLICopy

   kloudlite pipelines run acme/refresh --version 2 --input day=2026-10-21

2. Add clone="staging" to run the jobs in a copy of the environment staging, or environment="staging" to use it as it is.

Close-out

1. Make sure that pipelineVersion is 2 and that the state is queued or running.

List the runs of a pipeline

Reason for the task: Find a run, for example the newest run that a schedule started.

Job set-up

• Access: you. For a team, an active member.
• References: GET /v1/pipelines/{owner}/{pipeline}/runs, SDK pipelines.runs.

Procedure

1. Show the newest runs. The default is 50 runs, and the maximum is 200.

   PythonCopy

   for r in kl.pipelines.runs(owner="acme", pipeline="refresh", limit=10):    print(r.number, r.id, r.event, r.state)

   TypeScriptCopy

   for (const r of await kl.pipelines.runs({ owner: "acme", pipeline: "refresh", limit: 10 }))  console.log(r.number, r.id, r.doc.event, r.state);

   GoCopy

   runs, err := kl.Pipelines.Runs(kloudlite.ListRuns{Owner: "acme", Pipeline: "refresh", Limit: 10})if err != nil {    log.Fatal(err)}for _, r := range runs {    fmt.Println(r.Number, r.ID, r.Event, r.State)}

   RubyCopy

   kl.pipelines.runs(owner: "acme", pipeline: "refresh", limit: 10).each do |r|  puts [r.number, r.id, r.event, r.state].join(" ")end

   JavaCopy

   for (var r : kl.pipelines().runs(new Kloudlite.ListRuns().owner("acme").pipeline("refresh").limit(10)))    System.out.println(r.number() + " " + r.id() + " " + r.event() + " " + r.state());

   CLICopy

   kloudlite pipelines runs acme refresh --limit 10

Close-out

1. Make sure that the list starts with the newest run.

Show the state of a run and its jobs

Reason for the task: Find out if a run succeeded, and which job or step failed.

Job set-up

• Access: you. For a team, an active member.
• Conditions: you know the id of the run. See List the runs of a pipeline.
• References: GET /v1/pipelines/{owner}/{pipeline}/runs/{id}, SDK pipelines.get_run.

Procedure

1. Read the run, then show its state and the state of each job.

   PythonCopy

   run = kl.pipelines.get_run(owner="acme", pipeline="refresh", run="1760400000000-0a1b2c")print(run.state, run.detail)for j in run.jobs:    print(j["key"], j["state"], j.get("failedStep"), j.get("detail"))

   TypeScriptCopy

   const run = await kl.pipelines.getRun({ owner: "acme", pipeline: "refresh", run: "1760400000000-0a1b2c" });console.log(run.state, run.doc.detail);for (const j of run.jobs) console.log(j.key, j.state, j.failedStep, j.detail);

   GoCopy

   run, err := kl.Pipelines.GetRun(kloudlite.GetRun{Owner: "acme", Pipeline: "refresh", Run: "1760400000000-0a1b2c"})if err != nil {    log.Fatal(err)}fmt.Println(run.State, run.Detail)for _, j := range run.Jobs {    fmt.Println(j.Key, j.State, j.FailedStep, j.Detail)}

   RubyCopy

   run = kl.pipelines.get_run(owner: "acme", pipeline: "refresh", run: "1760400000000-0a1b2c")puts run.state, run.detailrun.jobs.each { |j| puts j.values_at("key", "state", "failedStep", "detail").join(" ") }

   JavaCopy

   var run = kl.pipelines().getRun(new Kloudlite.GetRun().owner("acme").pipeline("refresh").run("1760400000000-0a1b2c"));System.out.println(run.state() + " " + run.detail());for (var j : run.jobs()) System.out.println(j.get("key") + " " + j.get("state") + " " + j.get("failedStep"));

   CLICopy

   kloudlite pipelines get-run acme refresh 1760400000000-0a1b2c

Close-out

1. Make sure that the state is success. If it is failure, read detail of the run and failedStep of the failed job.

Read the log of a job

Reason for the task: Read the output of a job, while it runs or after it ended.

Job set-up

• Access: you. For a team, an active member.
• Conditions: you have the run handle from task 003.
• References: GET …/jobs/{index}/logs, SDK Run.logs, Run.follow.

Procedure

1. Read the whole log of the job load. Use the key of the job, or its index in jobs.

   PythonCopy

   print(run.logs(job="load"))

   TypeScriptCopy

   console.log(await run.logs({ job: "load" }));

   GoCopy

   out, err := run.Logs("load")if err != nil {    log.Fatal(err)}fmt.Print(out)

   RubyCopy

   puts run.logs(job: "load")

   JavaCopy

   System.out.print(run.logs("load"));

   CLICopy

   kloudlite pipelines logs acme refresh 1760400000000-0a1b2c load

2. Read the log of a running job as it grows. The call ends when the job ends.

   PythonCopy

   for chunk in run.follow(job="load"):    print(chunk, end="")

   TypeScriptCopy

   for await (const chunk of run.follow({ job: "load" })) process.stdout.write(chunk);

   GoCopy

   err = run.Follow(kloudlite.FollowLogs{Job: "load"}, func(chunk string) bool {    fmt.Print(chunk)    return true})if err != nil {    log.Fatal(err)}

   RubyCopy

   run.follow(job: "load") { |chunk| print chunk }

   JavaCopy

   run.follow("load").forEach(System.out::print);

   CLICopy

   kloudlite pipelines logs acme refresh 1760400000000-0a1b2c load --follow

Close-out

1. Make sure that the log shows a ▶ line for each step of the job.

Cancel a run

Reason for the task: Stop a run that is not needed, and release its sandboxes.

Job set-up

• Access: you. For a team, an active member.
• Conditions: the run is queued or running.
• References: POST …/runs/{id}/cancel, SDK Run.cancel, Run.wait.

Procedure

1. Send the cancel, then wait for the run to end.

   PythonCopy

   run.cancel()print(run.wait())

   TypeScriptCopy

   await run.cancel();console.log(await run.wait());

   GoCopy

   if err := run.Cancel(); err != nil {    log.Fatal(err)}state, err := run.Wait(kloudlite.WaitRun{})if err != nil {    log.Fatal(err)}fmt.Println(state)

   RubyCopy

   run.cancelputs run.wait

   JavaCopy

   run.cancel();System.out.println(run.waitFor());

   CLICopy

   kloudlite pipelines cancel-run acme refresh 1760400000000-0a1b2ckloudlite pipelines wait-run acme refresh 1760400000000-0a1b2c

Close-out

1. Make sure that the final state is cancelled, and that no job is running.

Troubleshooting