Points de terminaison Run API

Référence complète des points de terminaison REST des runs, incluant le listing paginé, les détails enrichis, les actions de cycle de vie, et les données sandbox/transcript nécessaires pour reproduire l’UI /runs via l’API.

14 min lire
apirunsworkflows

La Runs API reflète les pages liste /runs et détail de run du dashboard. Elle couvre le cycle de vie complet : lister, inspecter, mettre en pause, reprendre, annuler, redémarrer, arrêter proprement après le tour en cours, et récupérer les données sandbox/transcript qui alimentent l’UI de détail.

Notes de parité avec l’UI

  • Parité de liste : le point de terminaison de liste renvoie désormais des résumés de nom de workflow, le coût du run, l’état de PR, les métadonnées de progression et les infos de pagination par curseur.
  • Parité de détail : les réponses de détail de run incluent désormais des métadonnées d’étape enrichies telles que le nom d’affichage de l’outil, le modèle résolu, l’effort de réflexion, les résumés de sandbox, le contenu de version de prompt système, et les ID de sandbox actif/explorer.
  • Parité d’action : chaque action de run du dashboard a un point de terminaison REST : annuler, mettre en pause, reprendre, redémarrer, renommer, supprimer, suppression en masse et arrêt propre.

Objet Run

Le point de terminaison de liste renvoie une forme résumée de l’objet run. Les points de terminaison de détail renvoient les mêmes champs de premier niveau plus des données d’étape et de sandbox enrichies.

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

Valeurs de statut de run

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

Points de terminaison de lecture

GET /api/v1/runs/list

Liste les runs du projet authentifié. Ce point de terminaison est paginé par curseur afin que les clients API puissent reproduire exactement la navigation page par page du dashboard.

Paramètres de query :

  • limit (optionnel) - v2 (par défaut) : 1..200, par défaut 50. Opt-out v1 : 1..100, par défaut 50.
  • cursor (optionnel) - curseur opaque provenant du nextCursor (v2) ou pagination.nextCursor (v1) de la réponse précédente.
  • status (optionnel) - 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"

Réponse (v2 par défaut - enveloppe plate) :

{
  "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 (envoyer X-API-Version: 1) conserve le bloc pagination imbriqué pour la rétrocompatibilité :

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

GET /api/v1/runs/get

Récupère un seul run par ID Convex avec des données de détail enrichies pour l’écran de détail de run.

  • id (requis) - ID du document run
  • stepLimit (optionnel, par défaut 50, max 500)

La réponse inclut :

  • résumé du workflow et slug du repository
  • activeStepId, activeSandboxId, et explorerSandboxId
  • activeDurationMs et durationMs une fois terminé
  • résumés sandboxes du run
  • des steps enrichis avec le nom d’affichage de l’outil, le modèle résolu, l’effort de réflexion, le snapshot de persona, le résumé de sandbox et le contenu de version de prompt système

GET /api/v1/runs/detail

Alias rétrocompatible de /api/v1/runs/get. Accepte runId au lieu de id.

GET /api/v1/runs/by-number

Recherche un run par le numéro de run visible dans l’UI (par exemple, RUN-0530 / numéro de run 530).

  • runNumber (requis)
  • projectId (optionnel, doit correspondre au projet de la clé API si fourni)
  • stepLimit (optionnel, par défaut 50, max 500)

GET /api/v1/runs/by-workflow

Liste les runs d’un workflow spécifique avec pagination par curseur, du plus récent au plus ancien.

  • workflowId (requis) - ID du document workflow
  • limit (optionnel, par défaut 50, plage 1..200)
  • cursor (optionnel) - token de continuation opaque renvoyé en tant que nextCursor sur la page précédente. Omettez pour la page 1.

Renvoie l’enveloppe paginée v2 par défaut : { data: Run[], nextCursor: string | null, hasMore: boolean, requestId }. Les appelants legacy envoyant X-API-Version: 1 reçoivent la forme nue { data: Run[] } (toujours paginée par curseur ; retrait prévu le 2026-10-24).

GET /api/v1/runs/by-chain

Liste les runs d’une sprint chain spécifique avec pagination par curseur, du plus récent au plus ancien.

  • chainId (requis) - ID du document sprint chain
  • limit (optionnel, par défaut 50, plage 1..200)
  • cursor (optionnel) - token de continuation opaque renvoyé en tant que nextCursor sur la page précédente. Omettez pour la page 1.

Renvoie l’enveloppe paginée v2 par défaut : { data: Run[], nextCursor: string | null, hasMore: boolean, requestId }. Les appelants legacy envoyant X-API-Version: 1 reçoivent la forme nue { data: Run[] } (toujours paginée par curseur ; retrait prévu le 2026-10-24).

Champs de détail d’étape de run

Les points de terminaison de détail exposent des champs supplémentaires par étape utilisés directement par la timeline et l’UI d’inspection d’étape.

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

Points de terminaison de mutation / action

POST /api/v1/runs/start

Démarre un nouveau run de workflow.

POST /api/v1/runs/pause

Met en pause un run en cours d’exécution.

{ "runId": "..." }

POST /api/v1/runs/resume

Reprend un run en pause.

{ "runId": "..." }

POST /api/v1/runs/cancel

Annule un run en attente, en cours ou en pause.

{ "runId": "..." }

POST /api/v1/runs/restart

Redémarre un run terminé, échoué ou annulé.

{ "runId": "..." }

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

Définit stopAfterCurrentTurn afin que l’orchestrateur s’arrête une fois le tour actif terminé.

{ "runId": "..." }

POST /api/v1/runs/rename

Renomme un run.

POST /api/v1/runs/delete

Supprime un run (soft-delete).

POST /api/v1/runs/restore

Restaure un run supprimé en soft-delete.

POST /api/v1/runs/permanent-delete

Supprime définitivement un run.

POST /api/v1/runs/bulk-delete

Supprime plusieurs runs en soft-delete.

Points de terminaison sandbox liés

La page de détail de run affiche le transcript, l’explorateur de fichiers, le diff, l’aperçu et le chat de suivi à partir des données sandbox. Utilisez la Sandbox API pour ces éléments une fois que vous avez les ID de sandbox du 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

Informations

Pour les runs longs ou riches en transcript, gardez la requête de détail de run centrée sur la structure et les métadonnées d’étape, puis récupérez les transcripts sandbox séparément via les points de terminaison sandbox.