# Get a run's live view - **OpenAPI Version:** `3.2.0` - **API Version:** `3.1.0` - **Contact:** Syndai ## Contents **Operations** - [GET /api/v1/external/coding/runs/{coding\_run\_id}/live](#scalar-operation-get-apiv1externalcodingrunscoding-run-idlive) **Schemas** - [ExternalCodingRunLiveResponse](#scalar-schema-externalcodingrunliveresponse) - [ExternalRunActivityEventRead](#scalar-schema-externalrunactivityeventread) - [ExternalRunGoalRead](#scalar-schema-externalrungoalread) - [ExternalRunGoalLayerRead](#scalar-schema-externalrungoallayerread) - [ExternalRunGoalStepRead](#scalar-schema-externalrungoalstepread) - [ExternalCodingRunLivenessRead](#scalar-schema-externalcodingrunlivenessread) - [ExternalCodingRunPauseRead](#scalar-schema-externalcodingrunpauseread) - [ExternalCodingPendingHitlRequestRead](#scalar-schema-externalcodingpendinghitlrequestread) - [ExternalCodingConnectionAskRead](#scalar-schema-externalcodingconnectionaskread) - [ExternalCodingHitlInputRead](#scalar-schema-externalcodinghitlinputread) - [ExternalCodingHitlFreeTextPolicyRead](#scalar-schema-externalcodinghitlfreetextpolicyread) - [ExternalCodingHitlOptionRead](#scalar-schema-externalcodinghitloptionread) - [WebsiteApprovalDetails](#scalar-schema-websiteapprovaldetails) - [ExternalRunSteerMessageRead](#scalar-schema-externalrunsteermessageread) - [ExternalRunValidationCommandRead](#scalar-schema-externalrunvalidationcommandread) - [ProblemDetail](#scalar-schema-problemdetail) - [ExternalErrorCode](#scalar-schema-externalerrorcode) ## Servers - **URL:** `https://api.syndai.ai` ## Authentication - **CustomerApiKey**: HTTP bearer (`API Key`) Customer API key sent as a bearer token ## Tags ### Runs A run is one coding task Syndai carries from a prompt to a delivered change. Creating a run starts billable work; its `external_request_id` is the idempotency key, so a retry never starts a second run. Follow a run by streaming its events or polling `GET /runs/{id}`. Phases are open-ended: a run can pause to ask you something, so read `pending_hitl_requests` and answer through `/responses` rather than assuming a fixed order. ## Operations ### Get a run's live view - **Method:** `GET` - **Path:** `/api/v1/external/coding/runs/{coding_run_id}/live` - **Operation ID:** `getRunLive` - **Tags:** Runs Read a run's lightweight live view: its goal, current activity, brief and liveness. It is cheaper than `GET /runs/{id}` and meant for frequent polling. Pass `after` (the highest activity id you have seen) to receive only newer activity. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`coding_run_id` (required)**: `string`, format: `uuid` #### Query parameters - **`customer_id`**: `string | null`, format: `uuid` - **`after`**: `string | null` #### Responses ##### 200 Request fulfilled, document follows **Content type:** `application/json` [ExternalCodingRunLiveResponse](#scalar-schema-externalcodingrunliveresponse) **Generated example:** ```json { "activity": [ { "approx_ts": true, "attempt": "", "family": "", "hunk": "", "id": "", "kind": "", "label": "", "lines_added": 1, "lines_removed": 1, "ms": 1, "ok": true, "op": "", "parent": "", "phase": "", "ref": "", "tail": "", "target": "", "text": "", "tokens": 1, "ts": "", "wait": "" } ], "brief": "", "earliest_id": "", "goal": { "current_detail": "", "layers": [ { "files": [ "" ], "sequence": 1, "status": "", "title": "" } ], "repair_reason": "", "repair_round": 1, "steps": [ { "key": "", "label": "", "state": "" } ] }, "liveness": { "attempt": 1, "criteria_attention": false, "current_activity": { "additionalProperty": "anything" }, "last_activity_at": "", "max_attempts": 1, "reason": "", "source_id": "", "source_type": "", "state": "running", "stuck_detail": "", "stuck_reason": "" }, "pause": { "cause": "", "kind": "", "resume_at": "", "resume_kind": "" }, "pending_hitl_requests": [ { "connection": { "kind": "", "link": "", "names": [ "" ] }, "created_at": "", "defaults_at": "", "expires_at": "", "hitl_request_id": "", "inputs": [ { "context": "", "default_assumption": "", "default_option_ids": [ "" ], "free_text": { "enabled": true, "max_length": 1, "placeholder": "", "required_policy": "", "ui_mode": "" }, "input_id": "", "kind": "", "options": [ { "id": "", "label": "" } ], "prompt": "", "required": true } ], "request_kind": "", "schema_version": 1, "summary": "", "website_details": { "account_label": "", "action_class": "", "action_summary": "", "adapter_fingerprint": "", "adapter_spec_id": "", "domain": "", "estimated_cost_usd": 1, "expected_effect": "", "expires_at": "", "max_authorized_delta": { "additionalProperty": "anything" }, "money_or_credit_impact": { "additionalProperty": "anything" }, "reversibility": "", "risk_class": "", "robots_txt_violation": false, "session_identity_label": "", "session_window_expires_at": "", "tos_flagged_reason": "" } } ], "steer_messages": [ { "applied_at": "", "body": "", "created_at": "", "id": "", "orphaned_at": "" } ], "validation": [ { "cwd": "", "name": "", "p50_s": 1, "state": "" } ] } ``` ##### 400, 401, 403, 404 - `400` Bad request syntax or unsupported method - `401` Invalid or missing customer API key - `403` Insufficient scope or forbidden customer access - `404` Resource not found **Content type:** `application/problem+json` [ProblemDetail](#scalar-schema-problemdetail) RFC 7807 problem detail returned for public CaaS errors. **Generated example:** ```json { "code": "BUDGET_EXHAUSTED", "detail": null, "existing_run_id": null, "instance": null, "status": 1, "title": "", "type": "about:blank", "additionalProperty": "anything" } ``` ##### 429 Rate limit exceeded **Headers:** - **`Retry-After`** Seconds to wait before retrying the request `integer` **Content type:** `application/problem+json` [ProblemDetail](#scalar-schema-problemdetail) RFC 7807 problem detail returned for public CaaS errors. [Generated example](#scalar-example-2) ##### default Unexpected error **Content type:** `application/problem+json` [ProblemDetail](#scalar-schema-problemdetail) **Generated example:** ```json null ``` ## Schemas ### ExternalCodingRunLiveResponse **Type:** `object` - **`activity`**: array of [ExternalRunActivityEventRead](#scalar-schema-externalrunactivityeventread) - **`brief`**: `string | null` - **`earliest_id`**: `string | null` - **`goal`**: [ExternalRunGoalRead](#scalar-schema-externalrungoalread) | `null` - **`liveness`**: [ExternalCodingRunLivenessRead](#scalar-schema-externalcodingrunlivenessread) | `null` - **`pause`**: [ExternalCodingRunPauseRead](#scalar-schema-externalcodingrunpauseread) | `null` - **`pending_hitl_requests`**: array of [ExternalCodingPendingHitlRequestRead](#scalar-schema-externalcodingpendinghitlrequestread) - **`steer_messages`**: array of [ExternalRunSteerMessageRead](#scalar-schema-externalrunsteermessageread) - **`validation`**: array of [ExternalRunValidationCommandRead](#scalar-schema-externalrunvalidationcommandread) **Generated example:** ```json { "activity": [ { "approx_ts": true, "attempt": "", "family": "", "hunk": "", "id": "", "kind": "", "label": "", "lines_added": 1, "lines_removed": 1, "ms": 1, "ok": true, "op": "", "parent": "", "phase": "", "ref": "", "tail": "", "target": "", "text": "", "tokens": 1, "ts": "", "wait": "" } ], "brief": "", "earliest_id": "", "goal": { "current_detail": "", "layers": [ { "files": [ "" ], "sequence": 1, "status": "", "title": "" } ], "repair_reason": "", "repair_round": 1, "steps": [ { "key": "", "label": "", "state": "" } ] }, "liveness": { "attempt": 1, "criteria_attention": false, "current_activity": { "additionalProperty": "anything" }, "last_activity_at": "", "max_attempts": 1, "reason": "", "source_id": "", "source_type": "", "state": "running", "stuck_detail": "", "stuck_reason": "" }, "pause": { "cause": "", "kind": "", "resume_at": "", "resume_kind": "" }, "pending_hitl_requests": [ { "connection": { "kind": "", "link": "", "names": [ "" ] }, "created_at": "", "defaults_at": "", "expires_at": "", "hitl_request_id": "", "inputs": [ { "context": "", "default_assumption": "", "default_option_ids": [ "" ], "free_text": { "enabled": true, "max_length": 1, "placeholder": "", "required_policy": "", "ui_mode": "" }, "input_id": "", "kind": "", "options": [ { "id": "", "label": "" } ], "prompt": "", "required": true } ], "request_kind": "", "schema_version": 1, "summary": "", "website_details": { "account_label": "", "action_class": "", "action_summary": "", "adapter_fingerprint": "", "adapter_spec_id": "", "domain": "", "estimated_cost_usd": 1, "expected_effect": "", "expires_at": "", "max_authorized_delta": { "additionalProperty": "anything" }, "money_or_credit_impact": { "additionalProperty": "anything" }, "reversibility": "", "risk_class": "", "robots_txt_violation": false, "session_identity_label": "", "session_window_expires_at": "", "tos_flagged_reason": "" } } ], "steer_messages": [ { "applied_at": "", "body": "", "created_at": "", "id": "", "orphaned_at": "" } ], "validation": [ { "cwd": "", "name": "", "p50_s": 1, "state": "" } ] } ``` ### ExternalRunActivityEventRead **Type:** `object` - **`id` (required)**: `string` - **`kind` (required)**: `string` - **`ts` (required)**: `string`, format: `date-time` - **`approx_ts`**: `boolean | null` - **`attempt`**: `string | null` - **`family`**: `string | null` - **`hunk`**: `string | null` - **`label`**: `string | null` - **`lines_added`**: `integer | null` - **`lines_removed`**: `integer | null` - **`ms`**: `integer | null` - **`ok`**: `boolean | null` - **`op`**: `string | null` - **`parent`**: `string | null` - **`phase`**: `string | null` - **`ref`**: `string | null` - **`tail`**: `string | null` - **`target`**: `string | null` - **`text`**: `string | null` - **`tokens`**: `integer | null` - **`wait`**: `string | null` **Generated example:** ```json { "approx_ts": true, "attempt": "", "family": "", "hunk": "", "id": "", "kind": "", "label": "", "lines_added": 1, "lines_removed": 1, "ms": 1, "ok": true, "op": "", "parent": "", "phase": "", "ref": "", "tail": "", "target": "", "text": "", "tokens": 1, "ts": "", "wait": "" } ``` ### ExternalRunGoalRead **Type:** `object` - **`steps` (required)**: array of [ExternalRunGoalStepRead](#scalar-schema-externalrungoalstepread) - **`current_detail`**: `string | null` - **`layers`**: array of [ExternalRunGoalLayerRead](#scalar-schema-externalrungoallayerread) | `null` - **`repair_reason`**: `string | null` - **`repair_round`**: `integer | null` **Generated example:** ```json { "current_detail": "", "layers": [ { "files": [ "" ], "sequence": 1, "status": "", "title": "" } ], "repair_reason": "", "repair_round": 1, "steps": [ { "key": "", "label": "", "state": "" } ] } ``` ### ExternalRunGoalLayerRead **Type:** `object` - **`sequence` (required)**: `integer` - **`status` (required)**: `string` - **`title` (required)**: `string` - **`files`**: `array of string` **Generated example:** ```json { "files": [ "" ], "sequence": 1, "status": "", "title": "" } ``` ### ExternalRunGoalStepRead **Type:** `object` - **`key` (required)**: `string` - **`label` (required)**: `string` - **`state` (required)**: `string` **Generated example:** ```json { "key": "", "label": "", "state": "" } ``` ### ExternalCodingRunLivenessRead **Type:** `object` - **`state` (required)**: `string`, possible values: `"running", "waiting_on_approval", "waiting_on_input", "blocked", "stuck", "terminal", "waiting_on_review", "queued"` - **`attempt`**: `integer | null` - **`criteria_attention`**: `boolean`, default: `false` - **`current_activity`**: `object | null` - **`last_activity_at`**: `string | null`, format: `date-time` - **`max_attempts`**: `integer | null` - **`reason`**: `string | null` - **`source_id`**: `string | null` - **`source_type`**: `string | null` - **`stuck_detail`**: `string | null` - **`stuck_reason`**: `string | null` **Generated example:** ```json { "attempt": 1, "criteria_attention": false, "current_activity": { "additionalProperty": "anything" }, "last_activity_at": "", "max_attempts": 1, "reason": "", "source_id": "", "source_type": "", "state": "running", "stuck_detail": "", "stuck_reason": "" } ``` ### ExternalCodingRunPauseRead **Type:** `object` - **`kind` (required)**: `string` Why the run is paused. Current values: "usage\_exhausted" (provider usage window exhausted; auto-resumes at resume\_at when known), "credential\_disconnected" (a connected credential needs reconnecting), and "infra\_fault" (a fault on our side; see cause). Additional kinds may be added over time; clients must tolerate unknown values and degrade to a generic paused state. - **`cause`**: `string | null` - **`resume_at`**: `string | null`, format: `date-time` - **`resume_kind`**: `string | null` **Generated example:** ```json { "cause": "", "kind": "", "resume_at": "", "resume_kind": "" } ``` ### ExternalCodingPendingHitlRequestRead **Type:** `object` - **`created_at` (required)**: `string`, format: `date-time` - **`hitl_request_id` (required)**: `string`, format: `uuid` - **`inputs` (required)**: array of [ExternalCodingHitlInputRead](#scalar-schema-externalcodinghitlinputread) - **`request_kind` (required)**: `string` - **`schema_version` (required)**: `integer` - **`summary` (required)**: `string` - **`connection`**: [ExternalCodingConnectionAskRead](#scalar-schema-externalcodingconnectionaskread) | `null` - **`defaults_at`**: `string | null`, format: `date-time` - **`expires_at`**: `string | null`, format: `date-time` - **`website_details`**: [WebsiteApprovalDetails](#scalar-schema-websiteapprovaldetails) | `null` **Generated example:** ```json { "connection": { "kind": "", "link": "", "names": [ "" ] }, "created_at": "", "defaults_at": "", "expires_at": "", "hitl_request_id": "", "inputs": [ { "context": "", "default_assumption": "", "default_option_ids": [ "" ], "free_text": { "enabled": true, "max_length": 1, "placeholder": "", "required_policy": "", "ui_mode": "" }, "input_id": "", "kind": "", "options": [ { "id": "", "label": "" } ], "prompt": "", "required": true } ], "request_kind": "", "schema_version": 1, "summary": "", "website_details": { "account_label": "", "action_class": "", "action_summary": "", "adapter_fingerprint": "", "adapter_spec_id": "", "domain": "", "estimated_cost_usd": 1, "expected_effect": "", "expires_at": "", "max_authorized_delta": { "additionalProperty": "anything" }, "money_or_credit_impact": { "additionalProperty": "anything" }, "reversibility": "", "risk_class": "", "robots_txt_violation": false, "session_identity_label": "", "session_window_expires_at": "", "tos_flagged_reason": "" } } ``` ### ExternalCodingConnectionAskRead **Type:** `object` - **`kind` (required)**: `string` - **`link` (required)**: `string` - **`names` (required)**: `array of string` **Generated example:** ```json { "kind": "", "link": "", "names": [ "" ] } ``` ### ExternalCodingHitlInputRead **Type:** `object` - **`input_id` (required)**: `string` - **`kind` (required)**: `string` - **`prompt` (required)**: `string` - **`required` (required)**: `boolean` - **`context`**: `string | null` - **`default_assumption`**: `string | null` - **`default_option_ids`**: `array of string` - **`free_text`**: [ExternalCodingHitlFreeTextPolicyRead](#scalar-schema-externalcodinghitlfreetextpolicyread) | `null` - **`options`**: array of [ExternalCodingHitlOptionRead](#scalar-schema-externalcodinghitloptionread) **Generated example:** ```json { "context": "", "default_assumption": "", "default_option_ids": [ "" ], "free_text": { "enabled": true, "max_length": 1, "placeholder": "", "required_policy": "", "ui_mode": "" }, "input_id": "", "kind": "", "options": [ { "id": "", "label": "" } ], "prompt": "", "required": true } ``` ### ExternalCodingHitlFreeTextPolicyRead **Type:** `object` - **`enabled` (required)**: `boolean` - **`max_length`**: `integer | null` - **`placeholder`**: `string | null` - **`required_policy`**: `string | null` - **`ui_mode`**: `string | null` **Generated example:** ```json { "enabled": true, "max_length": 1, "placeholder": "", "required_policy": "", "ui_mode": "" } ``` ### ExternalCodingHitlOptionRead **Type:** `object` - **`id` (required)**: `string` - **`label` (required)**: `string` **Generated example:** ```json { "id": "", "label": "" } ``` ### WebsiteApprovalDetails **Type:** `object` - **`action_summary` (required)**: `string` - **`adapter_fingerprint` (required)**: `string` - **`adapter_spec_id` (required)**: `string` - **`domain` (required)**: `string` - **`expected_effect` (required)**: `string` - **`expires_at` (required)**: `string` - **`reversibility` (required)**: `string` - **`risk_class` (required)**: `string` - **`account_label`**: `string | null` - **`action_class`**: `string | null` - **`estimated_cost_usd`**: `number | null` - **`max_authorized_delta`**: `object` - **`money_or_credit_impact`**: `object` - **`robots_txt_violation`**: `boolean`, default: `false` - **`session_identity_label`**: `string | null` - **`session_window_expires_at`**: `string | null` - **`tos_flagged_reason`**: `string | null` **Generated example:** ```json { "account_label": "", "action_class": "", "action_summary": "", "adapter_fingerprint": "", "adapter_spec_id": "", "domain": "", "estimated_cost_usd": 1, "expected_effect": "", "expires_at": "", "max_authorized_delta": { "additionalProperty": "anything" }, "money_or_credit_impact": { "additionalProperty": "anything" }, "reversibility": "", "risk_class": "", "robots_txt_violation": false, "session_identity_label": "", "session_window_expires_at": "", "tos_flagged_reason": "" } ``` ### ExternalRunSteerMessageRead **Type:** `object` - **`body` (required)**: `string` - **`created_at` (required)**: `string`, format: `date-time` - **`id` (required)**: `string`, format: `uuid` - **`applied_at`**: `string | null`, format: `date-time` - **`orphaned_at`**: `string | null`, format: `date-time` **Generated example:** ```json { "applied_at": "", "body": "", "created_at": "", "id": "", "orphaned_at": "" } ``` ### ExternalRunValidationCommandRead **Type:** `object` - **`cwd` (required)**: `string` - **`name` (required)**: `string` - **`state` (required)**: `string` - **`p50_s`**: `number | null` **Generated example:** ```json { "cwd": "", "name": "", "p50_s": 1, "state": "" } ``` ### ProblemDetail **Type:** `object` RFC 7807 problem detail returned for public CaaS errors. - **`code` (required)**: `string`, possible values: `"BUDGET_EXHAUSTED", "QUOTA_EXCEEDED", "RUN_CONCURRENCY_LIMIT", "CUSTOMER_DISABLED", "REPO_NOT_BOUND", "IDEMPOTENCY_REPLAY", "CONFLICT", "MISSION_BUSY_RETRY", "HITL_REQUEST_CONFLICT", "HITL_REQUEST_SETTLED", "RUN_TERMINATED_BEFORE_RESPONSE", "INVALID_POLICY", "INVALID_SCOPE", "RATE_LIMITED", "INSTALLATION_INCOMPLETE", "SUBSCRIPTION_USAGE_UNAVAILABLE", "INVALID_TOKEN", "ROLE_REQUIRED", "PLAN_UPGRADE_REQUIRED", "EMAIL_MISMATCH", "EXPIRED_TOKEN", "NOT_FOUND", "OVERSCOPE_ACK_REQUIRED", "VERIFY_FAILED", "PUBLISH_IN_FLIGHT", "PUBLISH_UNSUPPORTED_REPO", "PUBLICATION_NOT_LIVE", "NO_APP_DATA", "FEATURE_REQUESTS_NEEDS_MEMBERS", "EMPTY_UPDATE", "BAD_CURSOR", "HUMAN_APPROVAL_REQUIRED", "PROTECTED_PATHS_MANAGED_ONLY", "RUN_IN_FLIGHT", "TEXT_EDIT_REFUSED", "CLI_UPGRADE_REQUIRED", "PRODUCTION_STEP_UP_REQUIRED", "PRICES_UPDATING", "GITHUB_UNAVAILABLE", "PUBLISH_NOT_SET_UP", "VERSION_NOT_DEPLOYED", "INTERNAL_ERROR"` Stable error codes surfaced to public CaaS clients. - **`status` (required)**: `integer` - **`title` (required)**: `string` - **`detail`**: `string | null`, default: `null` - **`existing_run_id`**: `string | null`, default: `null` - **`instance`**: `string | null`, default: `null` - **`type`**: `string`, default: `"about:blank"` **Generated example:** ```json { "code": "BUDGET_EXHAUSTED", "detail": null, "existing_run_id": null, "instance": null, "status": 1, "title": "", "type": "about:blank", "additionalProperty": "anything" } ``` ### ExternalErrorCode **Type:** `string`, possible values: `"BUDGET_EXHAUSTED", "QUOTA_EXCEEDED", "RUN_CONCURRENCY_LIMIT", "CUSTOMER_DISABLED", "REPO_NOT_BOUND", "IDEMPOTENCY_REPLAY", "CONFLICT", "MISSION_BUSY_RETRY", "HITL_REQUEST_CONFLICT", "HITL_REQUEST_SETTLED", "RUN_TERMINATED_BEFORE_RESPONSE", "INVALID_POLICY", "INVALID_SCOPE", "RATE_LIMITED", "INSTALLATION_INCOMPLETE", "SUBSCRIPTION_USAGE_UNAVAILABLE", "INVALID_TOKEN", "ROLE_REQUIRED", "PLAN_UPGRADE_REQUIRED", "EMAIL_MISMATCH", "EXPIRED_TOKEN", "NOT_FOUND", "OVERSCOPE_ACK_REQUIRED", "VERIFY_FAILED", "PUBLISH_IN_FLIGHT", "PUBLISH_UNSUPPORTED_REPO", "PUBLICATION_NOT_LIVE", "NO_APP_DATA", "FEATURE_REQUESTS_NEEDS_MEMBERS", "EMPTY_UPDATE", "BAD_CURSOR", "HUMAN_APPROVAL_REQUIRED", "PROTECTED_PATHS_MANAGED_ONLY", "RUN_IN_FLIGHT", "TEXT_EDIT_REFUSED", "CLI_UPGRADE_REQUIRED", "PRODUCTION_STEP_UP_REQUIRED", "PRICES_UPDATING", "GITHUB_UNAVAILABLE", "PUBLISH_NOT_SET_UP", "VERSION_NOT_DEPLOYED", "INTERNAL_ERROR"` Stable error codes surfaced to public CaaS clients.