Poll for completion

To check on a run from somewhere other than where you started it, such as a serverless function, a job queue, or a plain REST caller with no waiter, poll for its status yourself instead of relying on a blocking call. create_and_wait / createAndWait cover the common case: see Basic run for the full walkthrough. This guide covers doing that by hand instead.

Create, then poll `get`

create returns immediately with the run in pending state. Poll get by id until status reaches a terminal state (completed, failed, or cancelled); stop_reason appears only once it does.

import time

from seltz import AgentRunStatus

TERMINAL = {
    AgentRunStatus.AGENT_RUN_STATUS_COMPLETED,
    AgentRunStatus.AGENT_RUN_STATUS_FAILED,
    AgentRunStatus.AGENT_RUN_STATUS_CANCELLED,
}

run = client.agent.create(
    "What are the three most notable AI-company acquisitions announced in 2026?"
)

while run.status not in TERMINAL:
    time.sleep(10)
    run = client.agent.get(run.id)

print(run.status, run.stop_reason)

import { AgentRunStatus } from "seltz";

const TERMINAL = [AgentRunStatus.COMPLETED, AgentRunStatus.FAILED, AgentRunStatus.CANCELLED];

let run = await client.agent.create({
  query: "What are the three most notable AI-company acquisitions announced in 2026?",
});

while (!TERMINAL.includes(run.status)) {
  await new Promise((r) => setTimeout(r, 10000));
  run = await client.agent.get(run.id);
}

console.log(run.status, run.stopReason);

curl "https://api.seltz.ai/v1/agent/runs/$RUN_ID" \
  -H "x-api-key: $SELTZ_API_KEY"

run.status prints as a raw integer in Python (3 for completed) unless you compare against the named constant or call .Name(). This is the same gotcha Monitor’s run status has. Over REST and in TypeScript, status is already the lowercase/named form ("completed", AgentRunStatus.COMPLETED).

This is exactly what wait / createAndWait do for you. Reach for them first, and write your own loop only when you need to poll from somewhere the blocking call does not fit, or need a different interval than the SDK default of 10 seconds.

run = client.agent.wait(run_id, poll_interval=5, timeout=120)

const run = await client.agent.wait(runId, { pollIntervalMs: 5000, timeoutMs: 120000 });

timeout / timeoutMs bounds the wait client-side only. On expiry the SDK raises SeltzTimeoutError, but the run keeps executing server-side. Poll get again later, or see Cancel a run if you no longer want the result.

Next steps

List runs: paging this org’s runs, newest first
Cancel a run: best-effort cancellation, and why it can lose the race to completion
Reference: endpoints, fields, limits and errors
Agent API Reference: full REST request and response specification

Getting Started

Web Tools

Data

Tutorials

Integrations

SDKs

Poll for completion

Create, then poll `get`

Next steps

​Create, then poll get

​Next steps

Create, then poll `get`

Next steps