# Get the current state of a run (poll-friendly). GET https://services.leadconnectorhq.com/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". ## Authentication Send `Authorization: Bearer ` using: - **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `clientportal-ai.readonly` ## Parameters ### Header Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Version` | string | Yes | The API version. | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `projectId` | string | Yes | The project's id. | | `runId` | string | Yes | The run's id. | ## OpenAPI Specification ```json { "openapi": "3.0.0", "info": { "title": "HighLevel API", "version": "v3" }, "servers": [ { "url": "https://services.leadconnectorhq.com" } ], "paths": { "/ai-builder-api/projects/{projectId}/runs/{runId}": { "get": { "summary": "Get the current state of a run (poll-friendly).", "operationId": "getTheCurrentStateOfARunPollfriendly", "description": "Strictly tenant- and project-scoped. A run that exists under a\ndifferent `projectId` (or under a different tenant entirely)\nreturns `404 not_found` — never `403`, never the run record.\nThis matches OWASP API1:2023 Broken Object Level Authorization\nguidance: same shape for \"doesn't exist\" and \"not yours\".\n", "parameters": [ { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string", "pattern": "^prj_[A-Za-z0-9_-]+$" }, "description": "The project's id.", "example": "prj_5f0c2a3e" }, { "in": "path", "name": "runId", "required": true, "schema": { "type": "string", "pattern": "^run_[A-Za-z0-9_-]+$" }, "description": "The run's id.", "example": "run_8f3c2a91" }, { "name": "Version", "in": "header", "required": true, "description": "The API version.", "schema": { "type": "string", "enum": [ "v3" ] } } ], "responses": { "200": { "description": "Run state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRecord" } } } }, "404": { "description": "Run does not exist under this project (or at all).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearer": [ "clientportal-ai.readonly" ] } ] } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A sub-account access token: a Marketplace app's OAuth token or a Private Integration Token." } }, "schemas": { "RunRecord": { "type": "object", "required": [ "runId", "projectId", "prompt", "status", "createdAt", "updatedAt" ], "properties": { "runId": { "type": "string", "description": "The run.", "example": "run_8f3c2a91" }, "projectId": { "type": "string", "description": "The project the run belongs to.", "example": "prj_5f0c2a3e" }, "prompt": { "type": "string", "description": "What the run was asked to build or change.", "example": "Add a page listing upcoming events" }, "promptAuthor": { "description": "Who sent the prompt.", "type": "object", "required": [ "id", "name" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Authenticated user id captured when the prompt was submitted.", "example": "usr_9a8b7c" }, "name": { "type": "string", "description": "Display-name snapshot captured when the prompt was submitted.", "example": "Jane Doe" }, "avatarUrl": { "type": "string", "format": "uri", "description": "Profile-image snapshot captured when the prompt was submitted.", "example": "https://images.example.com/avatars/jane.png" } }, "title": "PromptAuthor" }, "status": { "description": "The run's status.", "type": "string", "enum": [ "queued", "running", "deploying", "ready", "failed", "cancelled", "needs_input" ], "title": "AgentRunStatus" }, "phase": { "type": "string", "description": "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`.", "enum": [ "init", "constitution", "specify", "clarify", "plan", "tasks", "analyze", "implement", "indexing", "build", "deploy", "ready", "failed" ], "example": "plan" }, "phaseStatus": { "type": "string", "description": "Phase-local status for the active Spec Kit phase.", "enum": [ "queued", "running", "awaiting_input", "terminal" ], "example": "running" }, "awaitingQuestion": { "description": "The question the run is paused on, while it waits for the creator.", "type": "object", "required": [ "capId", "question", "askedAt" ], "properties": { "capId": { "type": "string", "description": "The question's id: send it back as `capId` with the answer.", "example": "cap_portal_modules" }, "question": { "type": "string", "description": "The question to put to the creator.", "example": "Which areas should your portal have?" }, "choices": { "type": "array", "items": { "type": "string" }, "description": "The answers to offer, when it is a choice.", "example": [ "Courses", "Communities" ] }, "form": { "oneOf": [ { "type": "object", "description": "The record-fields form on `awaitingQuestion.form`. The answer `value`\nis `JSON.stringify({ fields: [{ label, type, options? }], show: [label, …] })`\n(`fields` = the NEW fields, `show` = every field clients see); as the\neditor (`edit: true`) it also carries `edits` and has `show` only when\nwhat clients see changed.\n", "required": [ "kind", "fields", "types" ], "properties": { "kind": { "type": "string", "enum": [ "record_fields" ], "description": "Always `record_fields`.", "example": "record_fields" }, "recordType": { "type": "object", "required": [ "label", "exists" ], "properties": { "label": { "type": "string", "maxLength": 60, "description": "Its name.", "example": "Policy" }, "exists": { "type": "boolean", "description": "True when the record type already exists.", "example": false } }, "description": "The record type the fields belong to." }, "existingFields": { "type": "array", "maxItems": 60, "items": { "type": "object", "required": [ "label", "type" ], "properties": { "label": { "type": "string", "description": "The field's name.", "example": "Policy number" }, "type": { "type": "string", "description": "The field's type.", "example": "TEXT" }, "options": { "type": "array", "items": { "type": "string" }, "description": "The choices, for a choice field.", "example": [ "Active", "Lapsed" ] }, "shown": { "type": "boolean", "description": "Clients see this field.", "example": true }, "namesRecords": { "type": "boolean", "description": "This field names each record.", "example": true } } }, "description": "The record type's fields today.", "example": [ { "label": "Policy number", "type": "TEXT", "shown": true } ] }, "fields": { "type": "array", "maxItems": 30, "items": { "type": "object", "required": [ "label", "type" ], "properties": { "label": { "type": "string", "maxLength": 60, "description": "The field's name.", "example": "Renewal date" }, "type": { "type": "string", "description": "The field's type.", "example": "DATE" }, "options": { "type": "array", "maxItems": 50, "items": { "type": "string" }, "description": "The choices, for a choice field.", "example": [ "Monthly", "Yearly" ] } } }, "description": "The new fields proposed.", "example": [ { "label": "Renewal date", "type": "DATE" } ] }, "edit": { "type": "boolean", "enum": [ true ], "description": "Set when this is the editor for an existing record type.", "example": true }, "types": { "type": "array", "description": "The field types the dropdown offers (server-owned).", "items": { "type": "object", "required": [ "value", "label" ], "properties": { "value": { "type": "string", "description": "The type, as an answer sends it.", "example": "TEXT" }, "label": { "type": "string", "description": "What the creator sees.", "example": "Single line" }, "withOptions": { "type": "boolean", "enum": [ true ], "description": "This type takes a list of choices.", "example": true }, "noConvert": { "type": "boolean", "enum": [ true ], "description": "An existing field cannot be changed to this type.", "example": true } } }, "example": [ { "value": "TEXT", "label": "Single line" } ] } }, "title": "RecordQuestionForm" }, { "type": "object", "description": "The media a request needs, on `awaitingQuestion.form`: one slot each,\npicked from the creator's GHL Media Library, pasted as a link, or\n(images only) generated. The answer `value` is\n`JSON.stringify({ \"\": [{ url, name, source }] | \"generate\" | [] })`\n(`source` is `library` or `link`; `[]` = skipped).\n", "required": [ "kind", "slots" ], "properties": { "kind": { "type": "string", "enum": [ "media" ], "description": "Always `media`.", "example": "media" }, "slots": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "required": [ "key", "label", "max", "accepts" ], "properties": { "key": { "type": "string", "description": "The slot's key in the answer.", "example": "hero" }, "label": { "type": "string", "description": "What to ask for.", "example": "Hero image" }, "purpose": { "type": "string", "description": "Where it will be used.", "example": "Top of the home page" }, "max": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many files the slot takes.", "example": 1 }, "accepts": { "type": "string", "enum": [ "image", "video", "file" ], "description": "The kind of media.", "example": "image" } } }, "description": "The media to collect, one slot each.", "example": [ { "key": "hero", "label": "Hero image", "max": 1, "accepts": "image" } ] } }, "title": "MediaQuestionForm" } ], "description": "Set when the answer is a form (record fields or media) rather than a choice; its `kind` says which." }, "details": { "type": "string", "description": "What the creator is agreeing to, shown under the question.", "example": "Your portal will use the Courses and Communities modules." }, "preview": { "type": "object", "additionalProperties": true, "description": "What the builder shows the creator beside this question. Display only: its shape follows the builder's screens and may change.", "example": {} }, "multiSelect": { "type": "boolean", "description": "Several choices may be picked.", "example": false }, "allowOther": { "type": "boolean", "description": "Adds a \"Something else\" choice that opens a box.", "example": true }, "input": { "type": "string", "enum": [ "short_text", "long_text" ], "description": "With no choices, one line or a paragraph.", "example": "short_text" }, "placeholder": { "type": "string", "description": "Hint text for a typed answer.", "example": "e.g. Weekly yoga classes" }, "askedAt": { "type": "string", "format": "date-time", "description": "When the run asked.", "example": "2026-10-15T09:32:00.000Z" } }, "title": "AgentRunAwaitingQuestion" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the run was created.", "example": "2026-10-15T09:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the run last changed.", "example": "2026-10-15T09:41:12.000Z" }, "previewUrl": { "type": "string", "format": "uri", "description": "Convenience field equal to `preview.primaryUrl`. Kept for\nsingle-service callers; multi-service callers should read\n`preview.services[]` for per-service URLs. This is the\ndurable customer-facing preview URL produced after a\nsuccessful build/deploy, not the live sandbox edit URL.\n", "example": "https://preview.example.com/my-portal" }, "preview": { "description": "Where to see what the run built.", "type": "object", "required": [ "primaryUrl", "services" ], "properties": { "primaryUrl": { "type": "string", "format": "uri", "description": "The URL the user opens — for multi-service web stacks, this is the primary (frontend) URL.", "example": "https://preview.example.com/my-portal" }, "services": { "type": "array", "items": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": "string", "description": "Service name as declared in the stack manifest.", "example": "web" }, "url": { "type": "string", "format": "uri", "description": "Where the service is served.", "example": "https://preview.example.com/my-portal" }, "imageUri": { "type": "string", "description": "The service's image.", "example": "registry.example.com/apps/web:run_8f3c2a91" }, "digest": { "type": "string", "description": "The image's digest.", "example": "sha256:3b1f0c9e2d7a" } }, "title": "ProvisionedService" }, "description": "Each service of the app and where it is served.", "example": [ { "name": "web", "url": "https://preview.example.com/my-portal" } ] } }, "title": "RunPreview" }, "livePreviewUrl": { "type": "string", "format": "uri", "deprecated": true, "description": "**Deprecated 2026-05-17. Will be removed 2026-11-17.**\nUse `sandboxUrl` instead — same value, accurate name.\n\nMisleadingly named: this is the SANDBOX URL (the agent's\nHMR/edit workshop), not the customer-facing preview. The\ncustomer preview lives at `previewUrl`. Co-populated with\n`sandboxUrl` for the deprecation window; readers should\nmigrate to `sandboxUrl`.\n", "example": "https://sbx-prj-5f0c2a3e.example.com" }, "livePreviewStatus": { "type": "string", "enum": [ "starting", "ready", "failed", "stopped" ], "deprecated": true, "description": "**Deprecated 2026-05-17. Will be removed 2026-11-17.**\nUse `sandboxStatus` instead.\n", "example": "ready" }, "sandboxUrl": { "type": "string", "format": "uri", "description": "URL of the project sandbox runtime.\nThis is the agent's compile + HMR workshop — NOT the\ncustomer-facing preview. The customer preview is at\n`previewUrl`, which surfaces in the builder UI's right\npane after the deploy gate succeeds.\n", "example": "https://sbx-prj-5f0c2a3e.example.com" }, "sandboxStatus": { "type": "string", "enum": [ "starting", "ready", "failed", "stopped" ], "description": "Current state of the sandbox dev server.", "example": "ready" }, "publishedUrl": { "type": "string", "format": "uri", "description": "URL of the production (\"Published\") runtime service for this project.\nPopulated when the project has\nbeen explicitly published at least once. Distinct from\n`previewUrl`/`preview.primaryUrl`, which always point at the\ndurable customer preview service that auto-updates on every\nsuccessful agent run. Absent for projects that have never\nbeen published — the FE renders \"Not published\" in that case.\n", "example": "https://my-portal.example.com" }, "publishedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the most recent publish, snapshotted\nonto the run at the moment it reached `ready`. Used by the\nFE to render staleness like \"Last published 5 hours ago\".\n", "example": "2026-10-14T18:02:00.000Z" }, "runsSinceLastPublish": { "type": "integer", "minimum": 0, "description": "Number of successful (status=ready) runs completed since\nthe project was last published. Reset to 0 by `publish`.\nSnapshotted onto each ready run so the FE can render a\nstaleness indicator without an extra round-trip. Absent\nfor projects that have never been published.\n", "example": 2 }, "summary": { "type": "string", "description": "AI-generated 1-line checkpoint description, snapshotted onto\nthe run record at `setStatus(\"ready\")` time. Sourced from\nthe agent's `completion` narrator event when present,\notherwise falls back to a deterministic prompt-derived\nstub. Read by Timeline + chat UI so users see \"what\nchanged in this checkpoint\" at a glance. Absent on\nnon-terminal or legacy runs.\n", "example": "Added an events page" }, "imageUri": { "type": "string", "description": "Image of the primary service.", "example": "registry.example.com/apps/web:run_8f3c2a91" }, "imageDigest": { "type": "string", "description": "Digest of the primary service's image.", "example": "sha256:3b1f0c9e2d7a" }, "failureMessage": { "type": "string", "description": "Why the run failed, in one line.", "example": "The build failed: pages/events.vue has a type error" }, "failure": { "type": "object", "description": "Structured failure taxonomy for a terminated run. Set in\ntandem with `failureMessage` (which is the human-readable\nderivation). Discriminated by `category`; consumers should\nbranch on `category` + `code` to render an actionable hint\ninstead of a generic \"Internal error\".\n", "required": [ "category", "code", "retryable", "responsibleModule" ], "properties": { "category": { "type": "string", "enum": [ "user_input", "config", "model", "build", "infra", "spec_kit", "transport", "runtime", "internal" ], "description": "What kind of failure it was.", "example": "build" }, "code": { "type": "string", "description": "Category-specific failure code. See the run-runtime\n`RunFailure` discriminated union for the per-category\ncode enum.\n", "example": "build_failed" }, "retryable": { "type": "boolean", "description": "Sending the same request again may succeed.", "example": false }, "responsibleModule": { "type": "string", "enum": [ "runtime", "dispatcher", "planner", "classifier", "spec_kit", "designer", "scaffolder", "builder", "verifier", "deployer", "infra", "model_provider", "transport", "unknown" ], "description": "The part of the builder that failed.", "example": "runtime" }, "userMessage": { "type": "string", "description": "For `category=user_input` — text safe to show the user verbatim.", "example": "Describe the page you want in a sentence or two." }, "details": { "type": "string", "description": "For `category=config` / `spec_kit` — operator-facing detail.", "example": "No stack manifest for this template" }, "provider": { "type": "string", "description": "For `category=model` — provider identifier (e.g. anthropic, openai).", "example": "anthropic" }, "attempt": { "type": "integer", "description": "For `category=model` — retry attempt index that ultimately gave up.", "example": 3 }, "failureHead": { "type": "string", "description": "For `category=build` — first chunk of compiler/test stderr.", "example": "pages/events.vue(12,5): error TS2339" }, "failureTail": { "type": "string", "description": "For `category=build` — last chunk of compiler/test stderr.", "example": "Found 1 error." }, "cause": { "type": "string", "description": "For `category=infra` — short cause description.", "example": "The sandbox did not become ready in time" }, "phase": { "type": "string", "description": "For `category=spec_kit` — phase id where the orchestrator halted.", "example": "plan" }, "stack": { "type": "string", "description": "For `category=internal` — first lines of the stack trace.", "example": "TypeError: Cannot read properties of undefined" }, "message": { "type": "string", "description": "For `category=runtime` — text safe to show the user verbatim.", "example": "The preview could not start." } } }, "metadata": { "type": "object", "additionalProperties": true, "description": "Reproducibility/debug metadata selected during run setup.", "properties": { "generationFailure": { "type": "object", "additionalProperties": true, "properties": { "code": { "type": "string", "enum": [ "provider_transient", "dispatch_failed", "scaffold_failed", "infra_failed", "agent_failed", "build_failed", "deploy_failed", "run_stalled", "pipeline_failed" ], "description": "The failure code.", "example": "provider_transient" }, "retryable": { "type": "boolean", "description": "Retrying may succeed.", "example": true }, "source": { "type": "string", "enum": [ "provider", "dispatch", "planning", "scaffold", "infra", "agent", "build", "deploy", "pipeline" ], "description": "Where it failed.", "example": "provider" }, "detail": { "type": "string", "description": "Detail for support.", "example": "The model provider was overloaded" } }, "description": "Why generating the app failed, when it did." }, "failedWorkspace": { "type": "object", "additionalProperties": true, "properties": { "preservedAt": { "type": "string", "format": "date-time", "description": "When it was kept.", "example": "2026-10-15T09:45:00.000Z" }, "uploadedFiles": { "type": "integer", "description": "How many files were kept.", "example": 128 }, "durationMs": { "type": "integer", "description": "How long keeping it took, in milliseconds.", "example": 2140 } }, "description": "The workspace kept from a failed run, for diagnosis." } } } }, "title": "RunRecord" }, "ApiError": { "type": "object", "required": [ "type", "title", "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri", "example": "about:blank", "description": "A URI identifying the kind of error." }, "title": { "type": "string", "example": "Request validation failed", "description": "Short summary of the kind of error." }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "example": 422, "description": "The HTTP status code." }, "detail": { "type": "string", "example": "One or more fields are invalid.", "description": "What went wrong with this request." }, "instance": { "type": "string", "example": "/api/v1/runs", "description": "The request path that failed." }, "code": { "type": "string", "example": "validation_error", "description": "Stable, machine-readable error code." }, "requestId": { "type": "string", "example": "req_01HXQ8Z6J9K2", "description": "The request's id, for support." }, "fieldErrors": { "type": "array", "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string", "example": "prompt", "description": "The invalid field, as a dotted path." }, "code": { "type": "string", "example": "required", "description": "Machine-readable reason." }, "message": { "type": "string", "example": "Prompt is required.", "description": "Human-readable reason." } }, "title": "FieldError" }, "description": "One entry per invalid field, when the request body was invalid.", "example": [ { "field": "name", "code": "too_long", "message": "name must be at most 120 characters" } ] } }, "title": "ApiError" } } } } ``` ## Code Examples **cURL** ```bash curl -L -X GET 'https://services.leadconnectorhq.com/ai-builder-api/projects//runs/' \ -H 'Authorization: Bearer ' \ -H 'Version: v3' ``` **Node.js** ```javascript const options = { method: 'GET', headers: { Authorization: 'Bearer ', Version: 'v3' } }; try { const response = await fetch('https://services.leadconnectorhq.com/ai-builder-api/projects//runs/', options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **Python** ```python import requests url = "https://services.leadconnectorhq.com/ai-builder-api/projects/{projectId}/runs/{runId}" headers = { "Authorization": "Bearer ", "Version": "v3" } response = requests.get(url, headers=headers) print(response.json()) ``` **PHP** ```php 'https://services.leadconnectorhq.com/ai-builder-api/projects//runs/', CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ', 'Version: v3', ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` **Java** ```java HttpResponse response = Unirest .get("https://services.leadconnectorhq.com/ai-builder-api/projects//runs/") .header("Authorization", "Bearer ") .header("Version", "v3") .asString(); ``` **Go** ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://services.leadconnectorhq.com/ai-builder-api/projects//runs/" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Version", "v3") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(string(body)) } ``` **Ruby** ```ruby require 'uri' require 'net/http' url = URI("https://services.leadconnectorhq.com/ai-builder-api/projects//runs/") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = "Bearer " request["Version"] = "v3" response = http.request(request) puts response.read_body ``` **PowerShell** ```powershell $headers = @{ "Authorization" = "Bearer " "Version" = "v3" } $response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/ai-builder-api/projects//runs/' -Method 'GET' -Headers $headers $response | ConvertTo-Json ```