Skip to main content
Version: v3

Get the current state of a run (poll-friendly).

GET 
/ai-builder-api/projects/:projectId/runs/:runId

Strictly tenant- and project-scoped. A run that exists under a different projectId (or under a different tenant entirely) returns 404 not_found — never 403, never the run record. This matches OWASP API1:2023 Broken Object Level Authorization guidance: same shape for "doesn't exist" and "not yours".

Request​

Version stringrequired

The API version.

Available optionsv3
projectId stringrequired

The project's id.

Possible values: Value must match regular expression ^prj_[A-Za-z0-9_-]+$

runId stringrequired

The run's id.

Possible values: Value must match regular expression ^run_[A-Za-z0-9_-]+$

application/json

Run state.

Schema
    runIdstringrequired

    The run.

    projectIdstringrequired

    The project the run belongs to.

    promptstringrequired

    What the run was asked to build or change.

    promptAuthorobject

    Who sent the prompt.

    statusAgentRunStatusrequired

    The run's status.

    Available optionsqueuedrunningdeployingreadyfailedcancelledneeds_input
    phasestring

    Internal Spec Kit phase for the active builder run. Stream-v6 maps this to user-facing data-status.data.phase values such as planning, clarifying, coding, and building.

    Available optionsinitconstitutionspecifyclarifyplantasksanalyzeimplementindexingbuilddeployready
    phaseStatusstring

    Phase-local status for the active Spec Kit phase.

    Available optionsqueuedrunningawaiting_inputterminal
    awaitingQuestionobject

    The question the run is paused on, while it waits for the creator.

    createdAtstring<date-time>required

    When the run was created.

    updatedAtstring<date-time>required

    When the run last changed.

    previewUrlstring<uri>

    Convenience field equal to preview.primaryUrl. Kept for single-service callers; multi-service callers should read preview.services[] for per-service URLs. This is the durable customer-facing preview URL produced after a successful build/deploy, not the live sandbox edit URL.

    previewobject

    Where to see what the run built.

    livePreviewUrlstring<uri>deprecated

    Deprecated 2026-05-17. Will be removed 2026-11-17. Use sandboxUrl instead — same value, accurate name.

    Misleadingly named: this is the SANDBOX URL (the agent's HMR/edit workshop), not the customer-facing preview. The customer preview lives at previewUrl. Co-populated with sandboxUrl for the deprecation window; readers should migrate to sandboxUrl.

    livePreviewStatusstringdeprecated

    Deprecated 2026-05-17. Will be removed 2026-11-17. Use sandboxStatus instead.

    Available optionsstartingreadyfailedstopped
    sandboxUrlstring<uri>

    URL of the project sandbox runtime. This is the agent's compile + HMR workshop — NOT the customer-facing preview. The customer preview is at previewUrl, which surfaces in the builder UI's right pane after the deploy gate succeeds.

    sandboxStatusstring

    Current state of the sandbox dev server.

    Available optionsstartingreadyfailedstopped
    publishedUrlstring<uri>

    URL of the production ("Published") runtime service for this project. Populated when the project has been explicitly published at least once. Distinct from previewUrl/preview.primaryUrl, which always point at the durable customer preview service that auto-updates on every successful agent run. Absent for projects that have never been published — the FE renders "Not published" in that case.

    publishedAtstring<date-time>

    ISO-8601 timestamp of the most recent publish, snapshotted onto the run at the moment it reached ready. Used by the FE to render staleness like "Last published 5 hours ago".

    runsSinceLastPublishinteger

    Number of successful (status=ready) runs completed since the project was last published. Reset to 0 by publish. Snapshotted onto each ready run so the FE can render a staleness indicator without an extra round-trip. Absent for projects that have never been published.

    Possible values: >= 0

    summarystring

    AI-generated 1-line checkpoint description, snapshotted onto the run record at setStatus("ready") time. Sourced from the agent's completion narrator event when present, otherwise falls back to a deterministic prompt-derived stub. Read by Timeline + chat UI so users see "what changed in this checkpoint" at a glance. Absent on non-terminal or legacy runs.

    imageUristring

    Image of the primary service.

    imageDigeststring

    Digest of the primary service's image.

    failureMessagestring

    Why the run failed, in one line.

    failureobject

    Structured failure taxonomy for a terminated run. Set in tandem with failureMessage (which is the human-readable derivation). Discriminated by category; consumers should branch on category + code to render an actionable hint instead of a generic "Internal error".

    metadataobject

    Reproducibility/debug metadata selected during run setup.