Embeddable

Jobs API reference

Poll GET /v1/jobs/:jobId to follow widget builds, AI edits, agent builds and restores, with status values, progress steps, results and failure codes.

5 min readPublished by Daniel Sternlicht on Nov 22, 2026, 10:57 AM UTCUpdated Nov 22, 2026

AI work runs in the background. When you create a widget, edit one, or create an agent with a prompt, the API answers right away with a jobId. Use the Jobs endpoint to find out when that work is done and what happened.

Polling is free. For keys and the shared error format, see API authentication, limits and errors.

Get a job

GET https://api.embeddable.co/v1/jobs/:jobId

Query parameterDefaultDescription
wait0Seconds to hold the request open until the job finishes, up to 50. The response comes back as soon as the job finishes, or when the time is up.
curl "https://api.embeddable.co/v1/jobs/job_1776081418601_b5049f7fd47c?wait=30" \
  -H "Authorization: Bearer emb_live_..."

A job from another workspace, or one that doesn't exist, returns 404 not_found.

Response

{
  "jobId": "job_1776081418601_b5049f7fd47c",
  "type": "widget_build",
  "widgetId": "Wbk5MPTfzx",
  "status": "completed",
  "progress": { "step": "complete", "message": "Build complete" },
  "result": {
    "buildId": "EmbeddableAppBuilder:557c1aeb-...",
    "widgetId": "Wbk5MPTfzx",
    "publishedFiles": 9,
    "published": true,
    "assistantReply": "I built a 3-tier pricing card with..."
  },
  "editorUrl": "https://embeddable.co/app/your-workspace/editor/Wbk5MPTfzx",
  "previewUrl": "https://embeddable.live/embed/Wbk5MPTfzx",
  "createdAt": "2026-11-22T10:12:03.000Z",
  "updatedAt": "2026-11-22T10:14:41.000Z"
}
FieldDescription
typewidget_build, widget_edit, agent_build or widget_restore.
widgetIdThe widget the job works on. Not set for agent builds.
statuspending, building, completed or failed.
progressThe current step, as step and a readable message.
resultWhat the job produced. Depends on the job type (see below).
errorOn failure, a readable reason.
errorCodeOn failure, a machine-readable reason (see below).
buildStatusWhile the job is still running and a compile has started, the compile's live status.
editorUrl, previewUrlLinks for the widget, when the job has a widgetId.

Status values

statusMeaning
pendingThe job was created and hasn't started yet.
buildingThe AI is writing code, or the widget is compiling or publishing.
completedDone. Read result.
failedStopped. Read errorCode and error.

completed and failed are final. Stop polling when you see either.

A job that stops reporting progress for 20 minutes is reported as failed with errorCode: "stale".

Results by job type

Widget build (widget_build)

From POST /v1/widgets. The job only completes after the new widget has compiled and been published, so its embed code works as soon as you see completed. You don't need to call publish.

result has buildId, widgetId, publishedFiles, published: true and assistantReply (the builder's reply, cleaned up for display).

Progress steps, in order: starting, building, publishing, complete. A build waiting in the compile queue shows building with the message "Waiting for the widget build to finish".

AI edit (widget_edit)

From POST /v1/widgets/:widgetId/edit. The change is saved as a draft and not published.

result fieldDescription
assistantReplyThe builder's reply.
filesChangedPaths that changed. Deleted files end in (deleted).
buildStatusSUCCEEDED when the draft compiled. not_needed when no code changed. unknown when code changed but no compile was started.
needsAnswertrue when the builder changed nothing and ended its reply with a question. Send your answer as the next edit.
draftAlways true. Publish with POST /v1/widgets/:widgetId/publish.
messageId, buildId, widgetIdIDs for the chat message, compile and widget.

If the draft doesn't compile, the job fails with build_failed. The edit is still saved, result is still filled in, and failureDetails has the compiler output.

Progress steps: loading, writing, compiling, complete.

Agent build (agent_build)

From POST /v1/agents with a prompt. result has buildId and widgetId (this is the agent's ID). Agents aren't compiled or published, and the builder may stop to ask a question. Open the editorUrl from the create response to see its reply and keep going. The job itself has no editorUrl for agents.

Restore (widget_restore)

Created by POST /v1/widgets/:widgetId/versions/:versionId/restore. That call already returns the full result, so you rarely need to poll it.

Failure codes

errorCodeWhat happenedWas a message used?
limit_reachedThe workspace has used its monthly messages.No
daily_limit_reachedA free workspace has used today's messages.No
widget_busyAnother AI turn was already running on the widget.No
ai_failedThe AI builder failed on our side.No
build_failedThe code was saved but didn't compile.Yes
publish_failedA new widget was built but couldn't be published. This includes a compile that failed. Open it in the editor before trying again.Yes
staleThe job stopped responding, usually because the server running it restarted.Maybe
server_errorSomething else went wrong on our side.Maybe
not_configuredOur server is missing a setting. Email us.No

When the answer is "Maybe", check usage with GET /v1/usage before you retry. Retrying a create with the same idempotency key returns the first job instead of building again, unless the first job failed with one of the "No" codes.

Polling pattern

Use wait instead of a tight loop. Most builds take one to five minutes.

async function waitForJob(jobId, apiKey) {
  while (true) {
    const res = await fetch(
      `https://api.embeddable.co/v1/jobs/${jobId}?wait=50`,
      { headers: { Authorization: `Bearer ${apiKey}` } },
    );
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const job = await res.json();
    if (job.status === "completed") return job;
    if (job.status === "failed") {
      throw new Error(`${job.errorCode}: ${job.error}`);
    }
  }
}

The same in a shell:

while true; do
  STATUS=$(curl -s "https://api.embeddable.co/v1/jobs/$JOB_ID?wait=50" \
    -H "Authorization: Bearer $EMBEDDABLE_API_KEY" | jq -r .status)
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
done

Questions? Email us through the contact page.

Did this answer your question?

Your feedback helps us improve.