Runs

Invoking a workflowCopy Anchor Link

const { run_id } = await a22a.runs.invoke({
  project: "acme",
  workflow: "summarise",
  input: { text: "…" }
});

The run is queued on the project's latest version and the call returns at once. Every invoke is its own run.

An invoke is rejected, and nothing is charged, if the workflow is not deployed, input is missing a field a prompt reads, a model is unavailable, you have no plan or no free run, or your credits cannot cover the run fee. See Errors.

Retrieving a runCopy Anchor Link

const run = await a22a.runs.retrieve(run_id);

{
  run_id: "4b3e…",
  status: "completed",
  steps: [
    { step_id: "extract", status: "completed", output: "…" },
    { step_id: "write", status: "completed", output: "…" }
  ]
}

status is one of the states. A completed step has an output, which is text, or JSON text if the step has an output shape. A failed step has an error.

Failed runsCopy Anchor Link

A step that fails for a temporary reason, such as no answer from the provider, is tried again, up to its retries, with a longer wait before each attempt. A retry calls the model again, so its answer can differ from the first attempt.

A step that cannot succeed fails straight away: the provider rejects the prompt, the answer does not match the step's output shape, or your credits cannot cover the call.

One failed step fails the run, and the run carries an error of its own. Steps already running finish and are charged; steps that have not started stay pending and never run.

{
  run_id: "4b3e…",
  status: "failed",
  error: "…",
  steps: [
    { step_id: "extract", status: "failed", error: "…" },
    { step_id: "write", status: "pending" }
  ]
}

To keep optional work from failing a run, put it in a workflow of its own.

Runs at a timeCopy Anchor Link

A run counts toward your plan's limit from invoke until it is completed or failed.

An invoke past the limit is rejected with 429 and too_many_runs. Nothing is queued; invoke again when a run ends.