Run-API-Endpunkte

Vollständige Referenz für die Run-REST-Endpunkte - inklusive paginierte Run-Auflistung, angereicherte Run-Details, Lifecycle-Aktionen und die Sandbox-/Transkript-Daten, die nötig sind, um die /runs-UI über die API nachzubilden.

14 Min. Lesezeit
apirunsworkflows

Die Runs-API spiegelt die /runs-Liste und die Run-Detail-Seiten des Dashboards. Sie deckt den gesamten Lifecycle ab: auflisten, inspizieren, pausieren, fortsetzen, abbrechen, neu starten, nach dem aktuellen Turn sauber stoppen und die Sandbox-/Transkript-Daten abrufen, die die Detail-UI speisen.

UI-Parität-Hinweise

  • Listen-Parität: Der List-Endpunkt liefert nun Workflow-Namens-Zusammenfassungen, Run-Kosten, PR-Status, Fortschritts-Metadaten und Cursor-Paginierungs-Infos.
  • Detail-Parität: Run-Detail-Antworten enthalten jetzt angereicherte Schritt-Metadaten wie Tool-Anzeigename, aufgelöstes Modell, Thinking-Effort, Sandbox-Zusammenfassungen, Inhalt der System-Prompt-Version sowie aktive Sandbox-/Explorer-IDs.
  • Aktions-Parität: Jede Dashboard-Run-Aktion hat einen REST-Endpunkt: cancel, pause, resume, restart, rename, delete, bulk delete und graceful stop.

Run-Objekt

Der List-Endpunkt liefert eine Zusammenfassungsform des Run-Objekts. Die Detail-Endpunkte liefern dieselben Top-Level-Felder plus angereicherte Schritt- und Sandbox-Daten.

{
  "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-Werte

  • pending
  • scheduled
  • running
  • paused
  • completed
  • failed
  • cancelled

Lese-Endpunkte

GET /api/v1/runs/list

Runs für das authentifizierte Projekt auflisten. Dieser Endpunkt ist Cursor-paginiert, sodass API-Clients die Seite-für-Seite-Navigation des Dashboards exakt nachbilden können.

Query-Parameter:

  • limit (optional) - v2 (Standard): 1..200, Default 50. v1-Opt-out: 1..100, Default 50.
  • cursor (optional) - Intransparenter Cursor aus dem nextCursor der vorherigen Antwort (v2) oder 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"

Antwort (v2-Standard - flacher 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 (Senden von X-API-Version: 1) behält den verschachtelten pagination-Block zur Abwärtskompatibilität:

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

GET /api/v1/runs/get

Einen einzelnen Run per Convex-ID abrufen, mit angereicherten Detail-Daten für die Run-Detail-Ansicht.

  • id (erforderlich) - Run-Dokument-ID
  • stepLimit (optional, Default 50, max 500)

Die Antwort enthält:

  • Workflow-Zusammenfassung und Repository-Slug
  • activeStepId, activeSandboxId und explorerSandboxId
  • activeDurationMs und abgeschlossenes durationMs
  • sandboxes-Zusammenfassungen für den Run
  • Angereicherte steps mit Tool-Anzeigename, aufgelöstem Modell, Thinking-Effort, Persona-Snapshot, Sandbox-Zusammenfassung und Inhalt der System-Prompt-Version

GET /api/v1/runs/detail

Abwärtskompatibler Alias für /api/v1/runs/get. Akzeptiert runId statt id.

GET /api/v1/runs/by-number

Einen Run per benutzerfreundlicher Run-Nummer abrufen, die in der UI angezeigt wird (z. B. RUN-0530 / Run-Nummer 530).

  • runNumber (erforderlich)
  • projectId (optional, muss bei Angabe zum Projekt des API-Schlüssels passen)
  • stepLimit (optional, Default 50, max 500)

GET /api/v1/runs/by-workflow

Runs für einen bestimmten Workflow mit Cursor-Paginierung auflisten, neueste zuerst.

  • workflowId (erforderlich) - Workflow-Dokument-ID
  • limit (optional, Default 50, Bereich 1..200)
  • cursor (optional) - Intransparenter Fortsetzungs-Token, der als nextCursor der vorherigen Seite geliefert wurde. Für Seite 1 weglassen.

Liefert standardmäßig den v2-paginierten Envelope: { data: Run[], nextCursor: string | null, hasMore: boolean, requestId }. Legacy-Aufrufer, die X-API-Version: 1 senden, erhalten die nackte { data: Run[] }-Form (weiterhin Cursor-paginiert; Sunset 2026-10-24).

GET /api/v1/runs/by-chain

Runs für eine bestimmte Sprint-Chain mit Cursor-Paginierung auflisten, neueste zuerst.

  • chainId (erforderlich) - Dokument-ID der Sprint-Chain
  • limit (optional, Default 50, Bereich 1..200)
  • cursor (optional) - Intransparenter Fortsetzungs-Token, der als nextCursor der vorherigen Seite geliefert wurde. Für Seite 1 weglassen.

Liefert standardmäßig den v2-paginierten Envelope: { data: Run[], nextCursor: string | null, hasMore: boolean, requestId }. Legacy-Aufrufer, die X-API-Version: 1 senden, erhalten die nackte { data: Run[] }-Form (weiterhin Cursor-paginiert; Sunset 2026-10-24).

Run-Schritt-Detail-Felder

Detail-Endpunkte stellen zusätzliche Pro-Schritt-Felder bereit, die direkt von der Timeline- und Schritt-Inspektor-UI verwendet werden.

{
  "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" }
}

Mutations-/Aktions-Endpunkte

POST /api/v1/runs/start

Einen neuen Workflow-Run starten.

POST /api/v1/runs/pause

Einen aktuell laufenden Run pausieren.

{ "runId": "..." }

POST /api/v1/runs/resume

Einen pausierten Run fortsetzen.

{ "runId": "..." }

POST /api/v1/runs/cancel

Einen ausstehenden, laufenden oder pausierten Run abbrechen.

{ "runId": "..." }

POST /api/v1/runs/restart

Einen abgeschlossenen, fehlgeschlagenen oder abgebrochenen Run neu starten.

{ "runId": "..." }

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

Setzt stopAfterCurrentTurn, sodass der Orchestrator nach Abschluss des aktiven Turns stoppt.

{ "runId": "..." }

POST /api/v1/runs/rename

Einen Run umbenennen.

POST /api/v1/runs/delete

Einen Run per Soft-Delete löschen.

POST /api/v1/runs/restore

Einen per Soft-Delete gelöschten Run wiederherstellen.

POST /api/v1/runs/permanent-delete

Einen Run dauerhaft löschen.

POST /api/v1/runs/bulk-delete

Mehrere Runs per Soft-Delete löschen.

Zugehörige Sandbox-Endpunkte

Die Run-Detail-Seite rendert Transkript, Datei-Explorer, Diff, Vorschau und Follow-up-Chat aus Sandbox-Daten. Verwenden Sie die Sandbox-API für diese Teile, sobald Sie die Sandbox-IDs des Runs haben.

  • 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

Halten Sie bei lange laufenden oder transkriptlastigen Runs die Run-Detail-Anfrage auf Struktur und Schritt-Metadaten beschränkt und holen Sie Sandbox-Transkripte separat über die Sandbox-Endpunkte ab.