Async executions and polling

Long-running model and workflow invocations can opt into async mode by appending ?async=true to the run endpoint. The submit returns in under 500ms with an executionId; you then either poll GET /api/executions/:id or receive a webhook callback when the run completes. This page documents the async lifecycle. For webhook-based delivery, see Webhooks.

When to use async

Video generation — Seedance runs can take 30–90 seconds. Async lets your client return a job id immediately and poll/listen.
Audio generation — Suno V5 typically takes 30–60s for two tracks.
Image generation with long pipelines — gpt-image-2 with high quality settings.
CI / cron — submit dozens of jobs in parallel, poll/wait at the end.

Compatibility

?async=true is only supported on HTTP+polling defs (Seedance variants, Suno V5, gpt-image-2). Other providers reject the query parameter:

Provider type	Supports async?
HTTP+polling (Seedance, Suno, gpt-image-2)	✅
Fal-backed (kling-v3-i2v, kling-o3-ref2v, kling-v3-motion, seedream-v5, nano-banana-2)	❌ → `400 ASYNC_NOT_SUPPORTED`
Anthropic-backed (claude-sonnet)	❌ → `400 ASYNC_NOT_SUPPORTED`

Use sync mode (omit ?async=true) for unsupported providers.

Submit an async run

curl -X POST "https://knouds.ai/api/models/seedance-2-0-full-access/run?async=true" \
  -H "x-api-key: $KNOUDS_KEY" -H "Content-Type: application/json" \
  -d '{"inputs":{"prompt":"...","duration":"5","type":"text-to-video"}}'

Response (returns in under 500ms):

{
  "_async": true,
  "executionId": "550e8400-e29b-41d4-a716-446655440000",
  "requestId": "kie_xyz789",
  "status": "processing",
  "webhookDelivery": {
    "configured": false
  },
  "pollUrl": "/api/executions/550e8400-e29b-41d4-a716-446655440000"
}

boolean

Always true — sentinel telling clients “this is an async submit, not a sync result”.

string

Knouds-generated UUID. Use this to poll status or to dedupe webhook deliveries.

string

Provider-side request id (Kie.ai’s taskId, Suno’s id, etc.) — useful for cross-referencing in provider logs.

string

processing immediately after submit. Transitions to completed, failed, cancelled, or cancel_requested over time.

object

{configured: true, url: '...'} if your key has a webhook configured; otherwise {configured: false}.

string

Convenience path you can hit to check status (same as /api/executions/{executionId}).

The same shape applies to POST /api/workflows/:slug/run?async=true.

Poll an execution

GET /api/executions/:id

Auth: capability execution:read (in every tier’s session AND api-key ceiling — even Free users can poll their own canvas async runs). Response:

{
  "executionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "requestId": "kie_xyz789",
  "durationMs": 47210,
  "result": {
    "videos": [
      { "url": "https://knouds-media.s3.amazonaws.com/media/abc.mp4" }
    ]
  },
  "webhookDelivery": {
    "configured": true,
    "url": "https://your-app.example.com/knouds-webhook",
    "attempts": 1,
    "deliveredAt": "2026-05-08T19:30:42.000Z",
    "lastError": null
  }
}

Status transitions:

processing → completed (success — result populated)
processing → failed (provider error — error.code populated)
processing → cancel_requested → cancelled (you called cancel; provider may have already finished, in which case result is also populated)

Cancel an in-flight execution

POST /api/executions/:id/cancel

Auth: capability execution:cancel (every tier).

curl -X POST "https://knouds.ai/api/executions/<uuid>/cancel" \
  -H "x-api-key: $KNOUDS_KEY"

Response:

{ "status": "cancel_requested" }

Sub-100ms latency in the normal case (in-memory abort signal). Falls back to a database flag for crash recovery — server restarts after submit but before completion still honor the cancel on the next polling tick.

Always-charge policy. Provider compute is consumed when you submit, so cancelling mid-flight does NOT refund credits. Trial grants also consume the slot. This applies to both sync and async runs.

If the execution has already finalized, you’ll get one of:

{ "status": "already_completed" }
{ "status": "already_failed" }
{ "status": "already_cancelled" }

Recommended pattern

// 1. Submit async
const submit = await fetch(
  `${BASE}/api/models/${id}/run?async=true`,
  { method: 'POST', headers, body: JSON.stringify({ inputs }) }
).then(r => r.json());

if (!submit._async) throw new Error('expected async submit');

// 2. Poll until terminal (or wait for webhook)
async function waitForExecution(executionId) {
  while (true) {
    const r = await fetch(`${BASE}/api/executions/${executionId}`, { headers });
    const row = await r.json();
    if (['completed', 'failed', 'cancelled'].includes(row.status)) return row;
    await new Promise(res => setTimeout(res, 2000)); // 2s interval
  }
}

const final = await waitForExecution(submit.executionId);
console.log(final.status, final.result);

For event-driven flows (no polling), configure a webhook on your key and skip the poll loop. See Webhooks.

Errors

Status	Code	Meaning
`400`	`ASYNC_NOT_SUPPORTED`	Provider doesn’t support polling. Use sync mode.
`404`	`EXECUTION_NOT_FOUND`	The UUID doesn’t resolve to a row owned by you (or it was deleted).
`500`	`PROVIDER_SUBMIT_FAILED`	Async submit hit upstream 4xx/5xx. Body includes `providerStatus` + `providerBody` so you don’t wait on a stuck `processing` row.
`500`	`PROVIDER_RESPONSE_INCOMPLETE`	Polling completed but the provider’s response didn’t contain the expected output. Credits NOT deducted.

Overview

Identity & Usage

Endpoints

Async & Webhooks

Async executions and polling

When to use async

Compatibility

Submit an async run

Poll an execution

Cancel an in-flight execution

Recommended pattern

Errors

​When to use async

​Compatibility

​Submit an async run

​Poll an execution

​Cancel an in-flight execution

​Recommended pattern

​Errors

When to use async

Compatibility

Submit an async run

Poll an execution

Cancel an in-flight execution

Recommended pattern

Errors