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.
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 parameter | Default | Description |
|---|---|---|
wait | 0 | Seconds 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"
}
| Field | Description |
|---|---|
type | widget_build, widget_edit, agent_build or widget_restore. |
widgetId | The widget the job works on. Not set for agent builds. |
status | pending, building, completed or failed. |
progress | The current step, as step and a readable message. |
result | What the job produced. Depends on the job type (see below). |
error | On failure, a readable reason. |
errorCode | On failure, a machine-readable reason (see below). |
buildStatus | While the job is still running and a compile has started, the compile's live status. |
editorUrl, previewUrl | Links for the widget, when the job has a widgetId. |
Status values
status | Meaning |
|---|---|
pending | The job was created and hasn't started yet. |
building | The AI is writing code, or the widget is compiling or publishing. |
completed | Done. Read result. |
failed | Stopped. 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 field | Description |
|---|---|
assistantReply | The builder's reply. |
filesChanged | Paths that changed. Deleted files end in (deleted). |
buildStatus | SUCCEEDED when the draft compiled. not_needed when no code changed. unknown when code changed but no compile was started. |
needsAnswer | true when the builder changed nothing and ended its reply with a question. Send your answer as the next edit. |
draft | Always true. Publish with POST /v1/widgets/:widgetId/publish. |
messageId, buildId, widgetId | IDs 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
errorCode | What happened | Was a message used? |
|---|---|---|
limit_reached | The workspace has used its monthly messages. | No |
daily_limit_reached | A free workspace has used today's messages. | No |
widget_busy | Another AI turn was already running on the widget. | No |
ai_failed | The AI builder failed on our side. | No |
build_failed | The code was saved but didn't compile. | Yes |
publish_failed | A new widget was built but couldn't be published. This includes a compile that failed. Open it in the editor before trying again. | Yes |
stale | The job stopped responding, usually because the server running it restarted. | Maybe |
server_error | Something else went wrong on our side. | Maybe |
not_configured | Our 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.
