Endpoint Run API

Riferimento completo per gli endpoint REST dei run, inclusi elenco paginato, dettagli arricchiti, azioni sul ciclo di vita e i dati sandbox/transcript necessari per riprodurre l’UI /runs tramite API.

14 min letto
apirunsworkflows

La Runs API rispecchia le pagine lista /runs e dettaglio run della dashboard. Copre l’intero ciclo di vita: elencare, ispezionare, mettere in pausa, riprendere, annullare, riavviare, fermare in modo controllato dopo il turno corrente e recuperare i dati sandbox/transcript che alimentano l’UI di dettaglio.

Note di parità con l’UI

  • Parità di lista: l’endpoint di lista ora restituisce riepiloghi del nome del workflow, costo del run, stato della PR, metadati di avanzamento e info di paginazione a cursore.
  • Parità di dettaglio: le risposte di dettaglio run ora includono metadati di step arricchiti come nome visualizzato dello strumento, modello risolto, sforzo di ragionamento, riepiloghi sandbox, contenuto della versione del prompt di sistema, e ID sandbox attivo/explorer.
  • Parità di azione: ogni azione run della dashboard ha un endpoint REST: annulla, metti in pausa, riprendi, riavvia, rinomina, elimina, eliminazione in blocco e stop controllato.

Oggetto Run

L’endpoint di lista restituisce una forma riassunta dell’oggetto run. Gli endpoint di dettaglio restituiscono gli stessi campi di primo livello più dati di step e sandbox arricchiti.

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

Valori di stato del run

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

Endpoint di lettura

GET /api/v1/runs/list

Elenca i run del progetto autenticato. Questo endpoint è paginato a cursore, così i client API possono riprodurre esattamente la navigazione pagina per pagina della dashboard.

Parametri di query:

  • limit (opzionale) - v2 (predefinito): 1..200, predefinito 50. Opt-out v1: 1..100, predefinito 50.
  • cursor (opzionale) - cursore opaco proveniente dal nextCursor (v2) o pagination.nextCursor (v1) della risposta precedente.
  • status (opzionale) - 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"

Risposta (v2 predefinita - envelope piatto):

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

L’opt-out v1 legacy (inviando X-API-Version: 1) mantiene il blocco pagination annidato per retrocompatibilità:

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

GET /api/v1/runs/get

Recupera un singolo run per ID Convex con dati di dettaglio arricchiti per la schermata di dettaglio run.

  • id (obbligatorio) - ID del documento run
  • stepLimit (opzionale, predefinito 50, max 500)

La risposta include:

  • riepilogo del workflow e slug del repository
  • activeStepId, activeSandboxId, e explorerSandboxId
  • activeDurationMs e durationMs a completamento
  • riepiloghi sandboxes del run
  • steps arricchiti con nome visualizzato dello strumento, modello risolto, sforzo di ragionamento, snapshot della persona, riepilogo sandbox e contenuto della versione del prompt di sistema

GET /api/v1/runs/detail

Alias retrocompatibile di /api/v1/runs/get. Accetta runId invece di id.

GET /api/v1/runs/by-number

Cerca un run tramite il numero di run mostrato nell’UI (ad esempio, RUN-0530 / numero run 530).

  • runNumber (obbligatorio)
  • projectId (opzionale, deve corrispondere al progetto della chiave API se fornito)
  • stepLimit (opzionale, predefinito 50, max 500)

GET /api/v1/runs/by-workflow

Elenca i run di un workflow specifico con paginazione a cursore, dal più recente.

  • workflowId (obbligatorio) - ID del documento workflow
  • limit (opzionale, predefinito 50, intervallo 1..200)
  • cursor (opzionale) - token di continuazione opaco restituito come nextCursor nella pagina precedente. Ometti per la pagina 1.

Restituisce l’envelope paginato v2 per impostazione predefinita: { data: Run[], nextCursor: string | null, hasMore: boolean, requestId }. I chiamanti legacy che inviano X-API-Version: 1ricevono la forma nuda { data: Run[] } (ancora paginata a cursore; dismissione prevista il 2026-10-24).

GET /api/v1/runs/by-chain

Elenca i run di una sprint chain specifica con paginazione a cursore, dal più recente.

  • chainId (obbligatorio) - ID del documento sprint chain
  • limit (opzionale, predefinito 50, intervallo 1..200)
  • cursor (opzionale) - token di continuazione opaco restituito come nextCursor nella pagina precedente. Ometti per la pagina 1.

Restituisce l’envelope paginato v2 per impostazione predefinita: { data: Run[], nextCursor: string | null, hasMore: boolean, requestId }. I chiamanti legacy che inviano X-API-Version: 1ricevono la forma nuda { data: Run[] } (ancora paginata a cursore; dismissione prevista il 2026-10-24).

Campi di dettaglio dello step di run

Gli endpoint di dettaglio espongono campi aggiuntivi per step usati direttamente dalla timeline e dall’UI di ispezione step.

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

Endpoint di mutazione / azione

POST /api/v1/runs/start

Avvia un nuovo run di workflow.

POST /api/v1/runs/pause

Mette in pausa un run in esecuzione.

{ "runId": "..." }

POST /api/v1/runs/resume

Riprende un run in pausa.

{ "runId": "..." }

POST /api/v1/runs/cancel

Annulla un run in attesa, in esecuzione o in pausa.

{ "runId": "..." }

POST /api/v1/runs/restart

Riavvia un run completato, fallito o annullato.

{ "runId": "..." }

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

Imposta stopAfterCurrentTurn così l’orchestratore si ferma al termine del turno attivo.

{ "runId": "..." }

POST /api/v1/runs/rename

Rinomina un run.

POST /api/v1/runs/delete

Elimina (soft-delete) un run.

POST /api/v1/runs/restore

Ripristina un run eliminato con soft-delete.

POST /api/v1/runs/permanent-delete

Elimina definitivamente un run.

POST /api/v1/runs/bulk-delete

Elimina (soft-delete) più run.

Endpoint sandbox correlati

La pagina di dettaglio run mostra transcript, esploratore file, diff, anteprima e chat di follow-up a partire dai dati sandbox. Usa la Sandbox API per questi elementi una volta ottenuti gli ID sandbox del run.

  • 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

Informazioni

Per run lunghi o ricchi di transcript, mantieni la richiesta di dettaglio run concentrata su struttura e metadati di step, poi recupera i transcript sandbox separatamente tramite gli endpoint sandbox.