Skip to main content
client.runs is the shared run API for workflow, agent, manual, and eval runs.

​
Start

const { id } = await client.run('workflows.extract-invoice', input);
For short jobs, ask the server to hold the request: 
const result = await client.run('workflows.extract-invoice', input, {
  waitForCompletion: 60,
});
For longer jobs, poll manually: 
const { id } = await client.run('agents.invoice-agent', input);
let run;
do {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  run = await client.runs.get(id);
} while (!run.finished);

​
Get

const run = await client.runs.get(id);
// { id, type, finished, execution, output?, files?, error?, timing, ... }
Add heavier optional sections with expand: 
const run = await client.runs.get(id, { expand: ['usage', 'execution'] });
console.log(run.output, run.usage, run.execution);

​
List

const { runs } = await client.runs.list({
  type: 'workflow',
  status: 'failed,cancelled',
  limit: 50,
});

​
Subresources

await client.runs.usage(id);
await client.runs.steps(id);
await client.runs.events(id);
await client.runs.trace.get(id);
await client.runs.feedback.get(id);
await client.runs.feedback.update(id, { body: 'Looks wrong', status: 'open' });

​
Artifacts

const { artifacts } = await client.runs.artifacts.list(id);
const bytes = await client.runs.artifacts.download(id, artifacts[0].path);
Artifacts are run-scoped snapshots. Reusable uploaded files are managed separately through client.files.

​
Cancel And Rerun

await client.runs.cancel(id);
const rerun = await client.rerun(id, { waitForCompletion: 60 });

​
Promote

Copy a completed run’s input, output, feedback, and expected artifacts into a dataset example on the same automation: 
const { exampleId, name } = await client.runs.promote(id, { name: 'golden-invoice' });