Run API Endpoints

Complete reference for run REST endpoints, including paginated run listing, enriched run details, lifecycle actions, and the sandbox/transcript data needed to reproduce the /runs UI over API.

14 min read

apirunsworkflows

The Runs API mirrors the dashboard's /runs list and run detail pages. It covers the full lifecycle: list, inspect, pause, resume, cancel, restart, gracefully stop after the current turn, and retrieve the sandbox/transcript data that powers the detail UI.

UI Parity Notes

List parity: the list endpoint now returns workflow name summaries, run cost, PR state, progress metadata, and cursor pagination info.
Detail parity: run detail responses now include enriched step metadata such as tool display name, resolved model, thinking effort, sandbox summaries, system prompt version content, and active/explorer sandbox IDs.
Action parity: every dashboard run action has a REST endpoint: cancel, pause, resume, restart, rename, delete, bulk delete, and graceful stop.

Run Object

The list endpoint returns a summary form of the run object. The detail endpoints return the same top-level fields plus enriched step and sandbox data.

{
  "id": "r_...",
  "_id": "r_...",
  "runNumber": 530,
  "name": "Add dark mode toggle",
  "status": "running",
  "source": "workflow",
  "prompt": "Add a dark mode toggle to the settings page",
  "githubRepoUrl": "https://github.com/org/repo",
  "repositorySlug": "org/repo",
  "branchName": "feature/dark-mode",
  "workflowId": "wf_...",
  "workflow": { "id": "wf_...", "_id": "wf_...", "name": "Main App Workflow" },
  "costUsd": 0.37,
  "currentIteration": 2,
  "maxIterations": 3,
  "currentStepLabel": "Running checker",
  "currentStepProgress": 0.42,
  "lastProgressAt": 1705316000000,
  "prStatus": "created",
  "prUrl": "https://github.com/org/repo/pull/42",
  "prNumber": 42,
  "ciChecks": {
    "status": "passed",
    "checkedAt": 1705316200000,
    "checks": [{ "name": "build", "status": "success", "url": "https://..." }]
  },
  "scheduledFor": 1705400000000,
  "timezone": "America/New_York",
  "recurrencePattern": "weekly",
  "stopAfterCurrentTurn": false,
  "startedAt": 1705312800000,
  "completedAt": null,
  "createdAt": 1705312600000
}

Run Status Values

pending
scheduled
running
paused
completed
failed
cancelled

Read Endpoints

GET /api/v1/runs/list

List runs for the authenticated project. This endpoint is cursor paginated so API clients can reproduce the dashboard's page-by-page navigation exactly.

Query parameters:

limit (optional) - v2 (default): 1..200, default 50. v1 opt-out: 1..100, default 50.
cursor (optional) - opaque cursor from the prior response's nextCursor (v2) or pagination.nextCursor (v1).
status (optional) - pending, scheduled, running, paused, completed, failed, cancelled

curl -H "Authorization: Bearer cc_live_..."   "https://<deployment>.convex.site/api/v1/runs/list?limit=25&status=running"

Response (v2 default - flat envelope):

{
  "data": [
    {
      "id": "r_...",
      "_id": "r_...",
      "runNumber": 530,
      "workflow": { "id": "wf_...", "_id": "wf_...", "name": "Main App Workflow" },
      "costUsd": 0.37,
      "status": "running",
      "currentStepLabel": "Running checker"
    }
  ],
  "nextCursor": "opaque-cursor",
  "hasMore": true
}

Legacy v1 opt-out (send X-API-Version: 1) keeps the nested pagination block for back-compat:

{
  "data": [ /* same items */ ],
  "pagination": {
    "nextCursor": "opaque-cursor",
    "hasMore": true
  }
}

GET /api/v1/runs/get

Retrieve a single run by Convex ID with enriched detail data for the run detail screen.

id (required) - run document ID
stepLimit (optional, default 50, max 500)

The response includes:

workflow summary and repository slug
activeStepId, activeSandboxId, and explorerSandboxId
activeDurationMs and finished durationMs
sandboxes summaries for the run
enriched steps with tool display name, resolved model, thinking effort, persona snapshot, sandbox summary, and system prompt version content

GET /api/v1/runs/detail

Backward-compatible alias for /api/v1/runs/get. AcceptsrunId instead of id.

GET /api/v1/runs/by-number

Look up a run by the human-facing run number shown in the UI (for example, RUN-0530 / run number 530).

runNumber (required)
projectId (optional, must match the API key's project if supplied)
stepLimit (optional, default 50, max 500)

GET /api/v1/runs/by-workflow

List runs for a specific workflow with cursor pagination, newest first.

workflowId (required) - workflow document ID
limit (optional, default 50, range 1..200)
cursor (optional) - opaque continuation token returned asnextCursor on the previous page. Omit for page 1.

Returns the v2 paginated envelope by default: { data: Run[], nextCursor: string | null, hasMore: boolean, requestId }. Legacy callers sending X-API-Version: 1 receive the bare { data: Run[] } shape (still cursor-paginated; sunset 2026-10-24).

GET /api/v1/runs/by-chain

List runs for a specific sprint chain with cursor pagination, newest first.

chainId (required) - sprint chain document ID
limit (optional, default 50, range 1..200)
cursor (optional) - opaque continuation token returned asnextCursor on the previous page. Omit for page 1.

Run Step Detail Fields

Detail endpoints expose extra per-step fields used directly by the timeline and step inspector UI.

{
  "id": "rs_...",
  "_id": "rs_...",
  "role": "designer",
  "status": "completed",
  "sandboxId": "sb_...",
  "toolDisplayName": "Claude Code",
  "resolvedModelId": "claude-opus-4-7",
  "thinkingEffort": "high",
  "thinkingEffortDisplay": "High",
  "personaVersionSnapshot": {
    "id": "pv_...",
    "_id": "pv_...",
    "version": 8,
    "name": "Designer",
    "cliId": "claude",
    "model": "claude-opus-4-7",
    "thinkingEffort": "high"
  },
  "sandbox": {
    "id": "sb_...",
    "_id": "sb_...",
    "sandboxId": "e2b_...",
    "status": "running"
  },
  "systemPromptVersion": {
    "id": "cv_...",
    "_id": "cv_...",
    "version": 12,
    "status": "active",
    "publishedAt": 1705312000000,
    "publishedBy": "user_...",
    "content": "You are the principal engineer..."
  },
  "tokenUsage": { "inputTokens": 12000, "outputTokens": 4500 },
  "testResults": { "total": 48, "passed": 45, "failed": 3, "skipped": 0 },
  "qualityScores": { "correctness": 90, "composite": 86 },
  "verdict": { "pass": true, "feedback": "Looks good" }
}

Mutation / Action Endpoints

POST /api/v1/runs/start

Start a new workflow run.

POST /api/v1/runs/pause

Pause a currently running run.

{ "runId": "..." }

POST /api/v1/runs/resume

Resume a paused run.

{ "runId": "..." }

POST /api/v1/runs/cancel

Cancel a pending, running, or paused run.

{ "runId": "..." }

POST /api/v1/runs/restart

Restart a completed, failed, or cancelled run.

{ "runId": "..." }

POST /api/v1/runs/request-graceful-stop

Set stopAfterCurrentTurn so the orchestrator stops after the active turn finishes.

{ "runId": "..." }

POST /api/v1/runs/rename

Rename a run.

POST /api/v1/runs/delete

Soft-delete a run.

POST /api/v1/runs/restore

Restore a soft-deleted run.

POST /api/v1/runs/permanent-delete

Permanently delete a run.

POST /api/v1/runs/bulk-delete

Soft-delete multiple runs.

Related Sandbox Endpoints

The run detail page renders transcript, file explorer, diff, preview, and follow-up chat from sandbox data. Use the Sandbox API for those pieces once you have the run's sandbox IDs.

GET /api/v1/sandboxes/list?runId=<runId>
GET /api/v1/sandboxes/messages?id=<sandboxId>
POST /api/v1/sandboxes/send-message
GET /api/v1/sandboxes/files, /file, /diff, /dev-server
POST /api/v1/sandboxes/dev-server/start

Info

For long-running or transcript-heavy runs, keep the run detail request focused on structure and step metadata, then fetch sandbox transcripts separately through the sandbox endpoints.