List an app's runs, newest first.
Returns the project's runs ordered newest-first by createdAt. The
FE calls this when a user reopens a project to rebuild the chat
history; pair with listAgentRunEvents per run to replay each
prompt's full event log.
Production-backed by Mongo (ai_builder_runs_records). Persists
across pod restarts and is shared across pods.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your access token.
clientportal-ai.OAuthPrivate IntegrationSub-Account TokenRequest
Headers
The API version.
v3v3Path Parameters
The project's id.
Possible values: Value must match regular expression ^prj_[A-Za-z0-9_-]+$
prj_5f0c2a3eQuery Parameters
Cap on the number of runs returned. Default 50. Pass 0 to
request every run (use sparingly — long-lived projects can
accumulate hundreds of follow-up runs).
Possible values: >= 0
5020Response
Project runs, newest first.
The project's runs, newest first.
The run.
run_8f3c2a91The project the run belongs to.
prj_5f0c2a3eWhat the run was asked to build or change.
Add a page listing upcoming eventsThe creator-facing text of this run's user bubble when it differs from prompt (see SubmitAgentRunRequest.displayText).
Fix these issuesWho sent the prompt.
Authenticated user id captured when the prompt was submitted.
usr_9a8b7cDisplay-name snapshot captured when the prompt was submitted.
Jane DoeProfile-image snapshot captured when the prompt was submitted.
https://images.example.com/avatars/jane.pngapp when an app sent the prompt rather than a person: an MCP client (name is "Claude", "Cursor"…) or an integration.
appappThe run's status.
queuedrunningdeployingreadyfailedcancelledneeds_inputInternal 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.
initconstitutionspecifyclarifyplantasksanalyzeimplementindexingbuilddeployreadyplanPhase-local status for the active Spec Kit phase.
queuedrunningawaiting_inputterminalrunningThe question the run is paused on, while it waits for the creator.
The question's id: send it back as capId with the answer.
cap_portal_modulesThe question to put to the creator.
Which areas should your portal have?The answers to offer, when it is a choice.
["Courses","Communities"]Set when the answer is a form (record fields or media) rather than a choice; its kind says which.
- RecordQuestionForm
- MediaQuestionForm
The record-fields form on awaitingQuestion.form. The answer value
is JSON.stringify({ fields: [{ label, type, options? }], show: [label, …] })
(fields = the NEW fields, show = every field clients see); as the
editor (edit: true) it also carries edits and has show only when
what clients see changed.
Always record_fields.
record_fieldsrecord_fieldsThe record type the fields belong to.
Its name.
Possible values: <= 60 characters
PolicyTrue when the record type already exists.
falseThe record type's fields today.
Possible values: <= 60
The field's name.
Policy numberThe field's type.
TEXTThe choices, for a choice field.
["Active","Lapsed"]Clients see this field.
trueThis field names each record.
trueThe new fields proposed.
Possible values: <= 30
The field's name.
Possible values: <= 60 characters
Renewal dateThe field's type.
DATEThe choices, for a choice field.
Possible values: <= 50
["Monthly","Yearly"]Set when this is the editor for an existing record type.
truetrueThe field types the dropdown offers (server-owned).
The type, as an answer sends it.
TEXTWhat the creator sees.
Single lineThis type takes a list of choices.
truetrueAn existing field cannot be changed to this type.
truetrueWhat the creator is agreeing to, shown under the question.
Your portal will use the Courses and Communities modules.What the builder shows the creator beside this question. Display only: its shape follows the builder's screens and may change.
What the builder shows the creator beside this question. Display only: its shape follows the builder's screens and may change.
Several choices may be picked.
falseAdds a "Something else" choice that opens a box.
trueWith no choices, one line or a paragraph.
short_textlong_textshort_textHint text for a typed answer.
e.g. Weekly yoga classesWhen the run asked.
2026-10-15T09:32:00.000ZThe questions a first build asks before it starts, while status is needs_input: answer them all with POST .../runs/{runId}/answers/batch, each by its capId.
The question's id: send it back as capId with its answer.
clarify.cp.nameWhat kind of question it is.
Planning questionThe question.
What should we call it?The answers to pick from; empty when freeText asks for a typed answer.
What to send back when this option is picked.
slateThe option as the creator reads it.
SlateA second line under the label.
Calm and neutralPicked unless the creator unpicks it.
falsePicking it means typing the answer instead.
falseA palette's colours, lightest to darkest.
["#364152","#697586"]The colour a palette leads with.
#364152The platforms the option exists on, when not all.
["mobile"]Several options may be picked.
falseNo options: the answer is typed.
trueHint text for a typed answer.
e.g. Forge FitnessA supporting line under the question.
The name your customers see when they sign in.The page of the intake form it belongs to.
appHow the builder draws it: cards, swatches, fonts, text and so on.
textThe platforms the question exists on, when not all.
["mobile"]Where the run is, in the words the builder shows the creator.
The step the run is on.
clarifyingWhere that step is.
queuedrunningawaiting_inputterminalawaiting_inputThe step in one sentence for the creator.
Answer the planning question to continue.The step's position, from 0.
2How many steps the run has.
6When the run reached this state.
2026-10-23T12:57:27.435ZWhen the run was created.
2026-10-15T09:30:00.000ZWhen the run last changed.
2026-10-15T09:41:12.000ZProblems the check found in a build written by an outside agent (externalAgent: true)
that still built and deployed. Fix them with another set of edits and run.
["pages/learn.vue: 'courses' is possibly undefined"]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.
https://preview.example.com/my-portalWhere to see what the run built.
The URL the user opens — for multi-service web stacks, this is the primary (frontend) URL.
https://preview.example.com/my-portalEach service of the app and where it is served.
Service name as declared in the stack manifest.
webWhere the service is served.
https://preview.example.com/my-portalThe service's image.
registry.example.com/apps/web:run_8f3c2a91The image's digest.
sha256:3b1f0c9e2d7aDeprecated 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.
https://sbx-prj-5f0c2a3e.example.comDeprecated 2026-05-17. Will be removed 2026-11-17.
Use sandboxStatus instead.
startingreadyfailedstoppedreadyURL 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.
https://sbx-prj-5f0c2a3e.example.comCurrent state of the sandbox dev server.
startingreadyfailedstoppedreadyURL 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.
https://my-portal.example.comISO-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".
2026-10-14T18:02:00.000ZNumber 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
2AI-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.
Added an events pageDeprecated: no longer returned. It named the builder's own image registry.
registry.example.com/apps/web:run_8f3c2a91Deprecated: no longer returned. It named the builder's own image.
sha256:3b1f0c9e2d7aWhy the run failed, in one line.
The build failed: pages/events.vue has a type errorStructured 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".
What kind of failure it was.
user_inputconfigmodelbuildinfraspec_kittransportruntimeinternalbuildCategory-specific failure code. See the run-runtime
RunFailure discriminated union for the per-category
code enum.
build_failedSending the same request again may succeed.
falseThe part of the builder that failed.
runtimedispatcherplannerclassifierspec_kitdesignerscaffolderbuilderverifierdeployerinframodel_providerruntimeFor category=user_input — text safe to show the user verbatim.
Describe the page you want in a sentence or two.For category=config / spec_kit — operator-facing detail.
No stack manifest for this templateFor category=model — provider identifier (e.g. anthropic, openai).
anthropicFor category=model — retry attempt index that ultimately gave up.
3For category=build — first chunk of compiler/test stderr.
pages/events.vue(12,5): error TS2339For category=build — last chunk of compiler/test stderr.
Found 1 error.For category=infra — short cause description.
The sandbox did not become ready in timeFor category=spec_kit — phase id where the orchestrator halted.
planFor category=internal — first lines of the stack trace. Never sent to a sub-account token.
TypeError: Cannot read properties of undefinedFor category=runtime — text safe to show the user verbatim.
The preview could not start.Deprecated: no longer returned. It held the builder's own debugging state.
Why generating the app failed, when it did.
The failure code.
provider_transientdispatch_failedscaffold_failedinfra_failedagent_failedbuild_faileddeploy_failedrun_stalledpipeline_failedprovider_transientRetrying may succeed.
trueWhere it failed.
providerdispatchplanningscaffoldinfraagentbuilddeploypipelineproviderDetail for support.
The model provider was overloadedWhy generating the app failed, when it did.
The workspace kept from a failed run, for diagnosis.
When it was kept.
2026-10-15T09:45:00.000ZHow many files were kept.
128How long keeping it took, in milliseconds.
2140The workspace kept from a failed run, for diagnosis.
Deprecated: no longer returned. It held the builder's own debugging state.