GuidesHandling async tasks

Polling

Poll for the result of an async tool execution.

The simplest way to get the result of a tool execution is to poll GET /v1/tools/executions/{toolExecutionId} until the status is terminal.

Both SDKs ship a pollExecutedTool helper that does this for you:

1import { pollExecutedTool } from "@videogen/sdk";
2
3const { toolExecutionId } = await client.tools.generateImage({
4  prompt: "A mountain at sunrise",
5});
6
7const response = await pollExecutedTool(client, toolExecutionId);
8
9if (response.status === "succeeded") {
10  console.log("File id:", response.results[0].fileId);
11}

The helper polls every 1.5 seconds (configurable via pollIntervalMs / poll_interval_ms) and returns once a terminal status is reached. Under the hood it’s a simple loop:

1async function pollExecutedTool(
2  client: Pick<VideoGenApiClient, "tools">,
3  toolExecutionId: string,
4  options?: { pollIntervalMs?: number; signal?: AbortSignal },
5): Promise<ExecutedTool> {
6  const pollIntervalMs = options?.pollIntervalMs ?? 1500;
7
8  while (true) {
9    options?.signal?.throwIfAborted();
10    const executed = await client.tools.getToolExecutionInfo({ toolExecutionId });
11
12    if (["succeeded", "failed", "cancelled"].includes(executed.status)) {
13      return executed;
14    }
15
16    await new Promise((r) => setTimeout(r, pollIntervalMs));
17  }
18}

When to use polling: good for scripts, CLI tools, or any situation where you can block and wait. For production systems, consider using webhooks instead.