waitForRun family: agent, action or format for a run id?

Pass family: "agent" for an Agent Completion run id, "action" for a schedule run and "format" for a Format run. The SDK docs say family is required and cannot be inferred, because the three families live behind different URL prefixes.

Everything here is from Waiting for runs and jobs and Agent Completions, read 2026-09-30.

Which family reads which URL?

What does a wrong family do?

The Agent Completions docs say an Action or Format run id will not resolve on the agent route: it returns 404 agent_run_not_found. The family also types the return value, so family: "format" resolves as PublicFormatRun.

What does the call look like?

Pass the client you created, because the module default client has no key. The default timeout is 10 minutes and it throws SumeRunTimeoutError when it elapses, without canceling the run.

import { createSumeClient, waitForRun } from "@sume-com/sdk";

const client = createSumeClient({ apiKey: process.env.SUME_API_KEY! });

const run = await waitForRun("agrun_demo", {
  client,
  family: "agent",
  onStatus: (status, snapshot) => console.log(status, snapshot.next_action),
});
console.log(run.status);

What if I would rather not poll?

Pass communication.webhook_url when you create the completion and take the signed agent.run.terminal event instead. Keep the poll as a fallback.

What does the receipt hold when it finishes?

A completed run fills output, by default the sume/action-run-output/v1 shape, with the agent's closing text in output.text and any generated media in output.images, output.videos, output.audio and output.files, plus artifacts and the spend in usage. The helpers resolve for any terminal status, so read status and error on the receipt rather than expecting a throw for a failed run.