# List runs - **OpenAPI Version:** `3.2.0` - **API Version:** `3.1.0` - **Contact:** Syndai ## Contents **Operations** - [GET /api/v1/external/coding/runs](#scalar-operation-get-apiv1externalcodingruns) **Schemas** - [ExternalCodingRunListResponse](#scalar-schema-externalcodingrunlistresponse) - [ExternalCodingRunRead](#scalar-schema-externalcodingrunread) - [ExternalRunAttentionRead](#scalar-schema-externalrunattentionread) - [ExternalSliceChainRead](#scalar-schema-externalslicechainread) - [ExternalSliceRead](#scalar-schema-externalsliceread) - [ExternalRunIngressRead](#scalar-schema-externalruningressread) - [ExternalCodingLandRead](#scalar-schema-externalcodinglandread) - [ExternalLandSecurityRead](#scalar-schema-externallandsecurityread) - [ExternalLandAccessRead](#scalar-schema-externallandaccessread) - [ExternalLandIntendedAccess](#scalar-schema-externallandintendedaccess) - [ExternalLandSecurityFixed](#scalar-schema-externallandsecurityfixed) - [ExternalLandSecurityHeld](#scalar-schema-externallandsecurityheld) - [RunLessonRead](#scalar-schema-runlessonread) - [MemoryGivenRead](#scalar-schema-memorygivenread) - [ExternalRunPrRead](#scalar-schema-externalrunprread) - [ExternalRunReadiness](#scalar-schema-externalrunreadiness) - [ExternalSubscriptionShareRead](#scalar-schema-externalsubscriptionshareread) - [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 ### List runs - **Method:** `GET` - **Path:** `/api/v1/external/coding/runs` - **Operation ID:** `listRuns` - **Tags:** Runs List coding runs, keyset-paginated over the full run set for a chunked, resumable bootstrap. Ordering is server-owned: newest `created_at`, then id descending, never reshuffled between pages, so a re-delivered row lands in exactly one page. `limit` is the page size (default 50, clamped to 200; always follow `next_cursor`). Pass the prior response's opaque `next_cursor` as `after` to fetch the next page; `next_cursor` is null at the end. Each run carries its per-viewer attention state. `coding_repository_id` narrows to one project; `needs=owner` to the runs waiting on the owner: a question, a held landing, or a finished pull request to review or put live. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Query parameters - **`limit`**: `integer`, default: `50` - **`after`**: `string | null` - **`customer_id`**: `string | null`, format: `uuid` - **`coding_repository_id`**: `string | null`, format: `uuid` - **`needs`**: `null | string`, possible values: `"owner", null` #### Responses ##### 200 Request fulfilled, document follows **Content type:** `application/json` [ExternalCodingRunListResponse](#scalar-schema-externalcodingrunlistresponse) **Example:** ```json { "next_cursor": null, "runs": [ { "artifact_retention_profile": "standard", "autonomy_mode": "review", "base_branch": "main", "coding_project_id": "c2e5f8a1-3b4d-4e6f-8a9b-1c2d3e4f5a6b", "coding_repository_id": "8a1d4e2f-5b6c-4d7e-8f9a-0b1c2d3e4f50", "created_at": "2026-10-27T09:00:00Z", "current_phase": "execute", "egress_profile": "managed_default", "external_request_id": "ticket-4812", "id": "3f9c2b7a-6d1e-4c8b-9a2f-1b7e5d4c3a21", "pr_url": null, "title": "Add a dark mode toggle to the header", "updated_at": "2026-10-27T09:04:12Z", "validation_iteration": 0 } ] } ``` ##### 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-1) ##### default Unexpected error **Content type:** `application/problem+json` [ProblemDetail](#scalar-schema-problemdetail) **Generated example:** ```json null ``` ## Schemas ### ExternalCodingRunListResponse **Type:** `object` - **`runs` (required)**: array of [ExternalCodingRunRead](#scalar-schema-externalcodingrunread) - **`next_cursor`**: `string | null` **Example:** ```json { "next_cursor": null, "runs": [ { "artifact_retention_profile": "standard", "autonomy_mode": "review", "base_branch": "main", "coding_project_id": "c2e5f8a1-3b4d-4e6f-8a9b-1c2d3e4f5a6b", "coding_repository_id": "8a1d4e2f-5b6c-4d7e-8f9a-0b1c2d3e4f50", "created_at": "2026-10-27T09:00:00Z", "current_phase": "execute", "egress_profile": "managed_default", "external_request_id": "ticket-4812", "id": "3f9c2b7a-6d1e-4c8b-9a2f-1b7e5d4c3a21", "pr_url": null, "title": "Add a dark mode toggle to the header", "updated_at": "2026-10-27T09:04:12Z", "validation_iteration": 0 } ] } ``` ### ExternalCodingRunRead **Type:** `object` - **`artifact_retention_profile` (required)**: `string` - **`coding_project_id` (required)**: `string`, format: `uuid` - **`created_at` (required)**: `string`, format: `date-time` - **`current_phase` (required)**: `string` - **`egress_profile` (required)**: `string` - **`external_request_id` (required)**: `string` - **`id` (required)**: `string`, format: `uuid` - **`updated_at` (required)**: `string`, format: `date-time` - **`validation_iteration` (required)**: `integer` - **`api_value_usd`**: `number | null` - **`attention`**: [ExternalRunAttentionRead](#scalar-schema-externalrunattentionread) | `null` - **`auto_run_kind`**: `string | null` - **`autonomy_mode`**: `string`, default: `"review"` - **`base_branch`**: `string | null` - **`cap_usd`**: `number | null` - **`chain`**: [ExternalSliceChainRead](#scalar-schema-externalslicechainread) | `null` - **`charged_usd`**: `number | null` - **`coding_repository_id`**: `string | null`, format: `uuid` - **`current_activity_kind`**: `string | null` - **`current_activity_since`**: `string | null` - **`current_activity_target`**: `string | null` - **`delivery_status`**: `string | null` - **`economy`**: `boolean`, default: `false` - **`effective_resolution_sha256`**: `string | null` - **`environment_id`**: `string | null`, format: `uuid` - **`failure_origin`**: `string | null` - **`harness_kind`**: `string | null` The harness chosen in the run's policy\_config, if any; null when no explicit choice was made. Open set — clients must tolerate unknown values. - **`ingress`**: [ExternalRunIngressRead](#scalar-schema-externalruningressread) | `null` - **`land`**: [ExternalCodingLandRead](#scalar-schema-externalcodinglandread) | `null` - **`last_stage`**: `string | null` - **`last_stage_at`**: `string | null`, format: `date-time` - **`lesson`**: [RunLessonRead](#scalar-schema-runlessonread) | `null` - **`memory_given`**: [MemoryGivenRead](#scalar-schema-memorygivenread) | `null` - **`origin`**: `string | null` - **`parent_coding_run_id`**: `string | null`, format: `uuid` - **`policy_contract_sha256`**: `string | null` - **`policy_resolved_at`**: `string | null`, format: `date-time` - **`pr_number`**: `integer | null` - **`pr_status`**: `string | null` - **`pr_url`**: `string | null` - **`preview_urls`**: `object` - **`prompt`**: `string | null` - **`pull_requests`**: array of [ExternalRunPrRead](#scalar-schema-externalrunprread) | `null` - **`readiness`**: [ExternalRunReadiness](#scalar-schema-externalrunreadiness) | `null` - **`redrive_count`**: `integer`, default: `0` - **`refund_under_review`**: `boolean`, default: `false` - **`refunded_usd`**: `number | null` - **`result_kind`**: `string | null` - **`schedule_id`**: `string | null`, format: `uuid` - **`schedule_kind`**: `string | null` - **`service_coverage`**: `array of object` - **`site_build`**: `string | null` - **`spec_review_mode`**: `string`, default: `"auto"` - **`stack_layer`**: `integer | null` - **`stack_total`**: `integer | null` - **`stopped`**: `boolean`, default: `false` - **`subscription_share`**: [ExternalSubscriptionShareRead](#scalar-schema-externalsubscriptionshareread) | `null` - **`terminal_summary`**: `object | null` - **`thread_id`**: `string | null`, format: `uuid` - **`title`**: `string | null` - **`validated_head_sha`**: `string | null` - **`work_usd`**: `number | null` **Generated example:** ```json { "api_value_usd": 1, "artifact_retention_profile": "", "attention": { "attention_at": "", "attention_class": 1, "note": "", "pause_kind": "", "resume_at": "", "state": "", "state_entered_at": "", "unread": false }, "auto_run_kind": "", "autonomy_mode": "review", "base_branch": "", "cap_usd": 1, "chain": { "root_run_id": "", "sequence": 1, "slices": [ { "feature_key": "", "run_id": "", "sequence": 1, "state": "", "title": "" } ], "total": 1 }, "charged_usd": 1, "coding_project_id": "", "coding_repository_id": "", "created_at": "", "current_activity_kind": "", "current_activity_since": "", "current_activity_target": "", "current_phase": "", "delivery_status": "", "economy": false, "effective_resolution_sha256": "", "egress_profile": "", "environment_id": "", "external_request_id": "", "failure_origin": "", "harness_kind": "", "id": "", "ingress": { "category": "", "excerpt": "", "inherited": false, "source": "", "url": "" }, "land": { "can_merge_anyway": false, "commit_url": "", "deploy_status": "", "head_sha": "", "landed_sha": "", "live_url": "", "owner_step": "", "reason": "", "revert_of_run_id": "", "reverted_by_run_id": "", "security": { "access": { "intended": [ { "quote": "", "sentence": "" } ], "members_see": [ "" ], "unchecked": [ "" ], "visitors_add": [ "" ], "visitors_see": [ "" ] }, "fixed": [ { "proved": true, "sentence": "" } ], "held": [ { "file": "", "proved": true, "sentence": "", "severity": "" } ], "state": "" }, "state": "", "strategy": "", "verified": true }, "last_stage": "", "last_stage_at": "", "lesson": { "text": "" }, "memory_given": { "answers": 1, "brief": true, "notes": 1 }, "origin": "", "parent_coding_run_id": "", "policy_contract_sha256": "", "policy_resolved_at": "", "pr_number": 1, "pr_status": "", "pr_url": "", "preview_urls": { "additionalProperty": "anything" }, "prompt": "", "pull_requests": [ { "base_branch": "", "branch": "", "draft": true, "feature_key": "", "pr_number": 1, "pr_status": "", "pr_url": "", "sequence": 1 } ], "readiness": { "clarifying_questions": [ "" ], "readiness": "" }, "redrive_count": 0, "refund_under_review": false, "refunded_usd": 1, "result_kind": "", "schedule_id": "", "schedule_kind": "", "service_coverage": [ { "additionalProperty": "anything" } ], "site_build": "", "spec_review_mode": "auto", "stack_layer": 1, "stack_total": 1, "stopped": false, "subscription_share": { "account_label": "", "final": true, "overage": true, "pct": 1, "provider": "", "window": "" }, "terminal_summary": { "additionalProperty": "anything" }, "thread_id": "", "title": "", "updated_at": "", "validated_head_sha": "", "validation_iteration": 1, "work_usd": 1 } ``` ### ExternalRunAttentionRead **Type:** `object` - **`attention_class` (required)**: `integer` - **`state` (required)**: `string` - **`attention_at`**: `string | null`, format: `date-time` - **`note`**: `string | null` - **`pause_kind`**: `string | null` - **`resume_at`**: `string | null`, format: `date-time` - **`state_entered_at`**: `string | null`, format: `date-time` - **`unread`**: `boolean`, default: `false` **Generated example:** ```json { "attention_at": "", "attention_class": 1, "note": "", "pause_kind": "", "resume_at": "", "state": "", "state_entered_at": "", "unread": false } ``` ### ExternalSliceChainRead **Type:** `object` - **`root_run_id` (required)**: `string` - **`sequence` (required)**: `integer` - **`total` (required)**: `integer` - **`slices`**: array of [ExternalSliceRead](#scalar-schema-externalsliceread) **Generated example:** ```json { "root_run_id": "", "sequence": 1, "slices": [ { "feature_key": "", "run_id": "", "sequence": 1, "state": "", "title": "" } ], "total": 1 } ``` ### ExternalSliceRead **Type:** `object` - **`feature_key` (required)**: `string` - **`sequence` (required)**: `integer` - **`state` (required)**: `string` - **`title` (required)**: `string` - **`run_id`**: `string | null` **Generated example:** ```json { "feature_key": "", "run_id": "", "sequence": 1, "state": "", "title": "" } ``` ### ExternalRunIngressRead **Type:** `object` - **`category` (required)**: `string` - **`source` (required)**: `string` - **`excerpt`**: `string | null` - **`inherited`**: `boolean`, default: `false` - **`url`**: `string | null` **Generated example:** ```json { "category": "", "excerpt": "", "inherited": false, "source": "", "url": "" } ``` ### ExternalCodingLandRead **Type:** `object` - **`state` (required)**: `string` - **`strategy` (required)**: `string` - **`can_merge_anyway`**: `boolean`, default: `false` - **`commit_url`**: `string | null` - **`deploy_status`**: `string | null` - **`head_sha`**: `string | null` - **`landed_sha`**: `string | null` - **`live_url`**: `string | null` - **`owner_step`**: `string | null` - **`reason`**: `string | null` - **`revert_of_run_id`**: `string | null`, format: `uuid` - **`reverted_by_run_id`**: `string | null`, format: `uuid` - **`security`**: [ExternalLandSecurityRead](#scalar-schema-externallandsecurityread) | `null` - **`verified`**: `boolean | null` **Generated example:** ```json { "can_merge_anyway": false, "commit_url": "", "deploy_status": "", "head_sha": "", "landed_sha": "", "live_url": "", "owner_step": "", "reason": "", "revert_of_run_id": "", "reverted_by_run_id": "", "security": { "access": { "intended": [ { "quote": "", "sentence": "" } ], "members_see": [ "" ], "unchecked": [ "" ], "visitors_add": [ "" ], "visitors_see": [ "" ] }, "fixed": [ { "proved": true, "sentence": "" } ], "held": [ { "file": "", "proved": true, "sentence": "", "severity": "" } ], "state": "" }, "state": "", "strategy": "", "verified": true } ``` ### ExternalLandSecurityRead **Type:** `object` - **`state` (required)**: `string` - **`access`**: [ExternalLandAccessRead](#scalar-schema-externallandaccessread) | `null` - **`fixed`**: array of [ExternalLandSecurityFixed](#scalar-schema-externallandsecurityfixed) - **`held`**: array of [ExternalLandSecurityHeld](#scalar-schema-externallandsecurityheld) **Generated example:** ```json { "access": { "intended": [ { "quote": "", "sentence": "" } ], "members_see": [ "" ], "unchecked": [ "" ], "visitors_add": [ "" ], "visitors_see": [ "" ] }, "fixed": [ { "proved": true, "sentence": "" } ], "held": [ { "file": "", "proved": true, "sentence": "", "severity": "" } ], "state": "" } ``` ### ExternalLandAccessRead **Type:** `object` - **`intended`**: array of [ExternalLandIntendedAccess](#scalar-schema-externallandintendedaccess) - **`members_see`**: `array of string` - **`unchecked`**: `array of string` - **`visitors_add`**: `array of string` - **`visitors_see`**: `array of string` **Generated example:** ```json { "intended": [ { "quote": "", "sentence": "" } ], "members_see": [ "" ], "unchecked": [ "" ], "visitors_add": [ "" ], "visitors_see": [ "" ] } ``` ### ExternalLandIntendedAccess **Type:** `object` - **`quote` (required)**: `string` - **`sentence` (required)**: `string` **Generated example:** ```json { "quote": "", "sentence": "" } ``` ### ExternalLandSecurityFixed **Type:** `object` - **`proved` (required)**: `boolean` - **`sentence` (required)**: `string` **Generated example:** ```json { "proved": true, "sentence": "" } ``` ### ExternalLandSecurityHeld **Type:** `object` - **`proved` (required)**: `boolean` - **`sentence` (required)**: `string` - **`severity` (required)**: `string` - **`file`**: `string | null` **Generated example:** ```json { "file": "", "proved": true, "sentence": "", "severity": "" } ``` ### RunLessonRead **Type:** `object` - **`text` (required)**: `string` **Generated example:** ```json { "text": "" } ``` ### MemoryGivenRead **Type:** `object` - **`brief` (required)**: `boolean` - **`notes` (required)**: `integer` - **`answers`**: `integer | null` **Generated example:** ```json { "answers": 1, "brief": true, "notes": 1 } ``` ### ExternalRunPrRead **Type:** `object` - **`base_branch` (required)**: `string` - **`branch` (required)**: `string` - **`draft` (required)**: `boolean` - **`sequence` (required)**: `integer` - **`feature_key`**: `string | null` - **`pr_number`**: `integer | null` - **`pr_status`**: `string | null` - **`pr_url`**: `string | null` **Generated example:** ```json { "base_branch": "", "branch": "", "draft": true, "feature_key": "", "pr_number": 1, "pr_status": "", "pr_url": "", "sequence": 1 } ``` ### ExternalRunReadiness **Type:** `object` - **`clarifying_questions` (required)**: `array of string` - **`readiness` (required)**: `string` **Generated example:** ```json { "clarifying_questions": [ "" ], "readiness": "" } ``` ### ExternalSubscriptionShareRead **Type:** `object` - **`final` (required)**: `boolean` - **`overage` (required)**: `boolean` - **`pct` (required)**: `number` - **`window` (required)**: `string` - **`account_label`**: `string | null` - **`provider`**: `string | null` **Generated example:** ```json { "account_label": "", "final": true, "overage": true, "pct": 1, "provider": "", "window": "" } ``` ### 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.