# List an app's runs, newest first. GET https://services.leadconnectorhq.com/ai-builder-api/projects/{projectId}/runs 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. ## 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. | ### Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `limit` | integer | No | 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). | ## 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": { "get": { "summary": "List an app's runs, newest first.", "operationId": "listAnAppsRunsNewestFirst", "description": "Returns the project's runs ordered newest-first by `createdAt`. The\nFE calls this when a user reopens a project to rebuild the chat\nhistory; pair with `listAgentRunEvents` per run to replay each\nprompt's full event log.\n\nProduction-backed by Mongo (`ai_builder_runs_records`). Persists\nacross pod restarts and is shared across pods.\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": "query", "name": "limit", "schema": { "type": "integer", "minimum": 0, "default": 50 }, "example": 20, "description": "Cap on the number of runs returned. Default 50. Pass `0` to\nrequest every run (use sparingly — long-lived projects can\naccumulate hundreds of follow-up runs).\n" }, { "name": "Version", "in": "header", "required": true, "description": "The API version.", "schema": { "type": "string", "enum": [ "v3" ] } } ], "responses": { "200": { "description": "Project runs, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunListResponse" } } } } }, "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": { "AgentRunListResponse": { "type": "object", "description": "Project's runs ordered newest-first by `createdAt`. Used by the FE\nto rebuild chat history on project-open.\n", "required": [ "runs" ], "properties": { "runs": { "type": "array", "description": "The project's runs, newest first.", "example": [ { "runId": "run_7b2c9e41", "projectId": "prj_5f0c2a3e", "prompt": "Add a class schedule page", "status": "ready", "createdAt": "2026-10-15T09:40:02.000Z", "updatedAt": "2026-10-15T09:41:12.000Z" } ], "items": { "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" }, "displayText": { "type": "string", "description": "The creator-facing text of this run's user bubble when it differs from `prompt` (see SubmitAgentRunRequest.displayText).", "example": "Fix these issues" }, "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" }, "checkProblems": { "type": "array", "items": { "type": "string" }, "description": "Problems the check found in a build written by an outside agent (`externalAgent: true`)\nthat still built and deployed. Fix them with another set of edits and run.\n", "example": [ "pages/learn.vue: 'courses' is possibly undefined" ] }, "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" }, "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. Never sent to a sub-account token.", "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." } } } }, "title": "RunRecord" } } }, "title": "AgentRunListResponse" } } } } ``` ## 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" 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 ```