Lancer un run

Un run exécute un agent une fois, avec l'entrée que vous fournissez. Il s'exécute en arrière-plan : POST /v1/runs répond en 202 dès que le run est mis en file, avant qu'il ait produit quoi que ce soit.

POST /v1/runs

Un champ inconnu est refusé (unknown_parameter) ; une valeur de mauvaise forme l'est aussi (invalid_parameter, param nommant le champ ou, pour un message de la liste, input.0.content).

curl https://leem-api.lcom-corp.com/v1/runs \
  -X POST \
  -H "Authorization: Bearer $LEEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent": "agt_01k6examplea0000000000000", "input": "Résume le ticket #482.", "metadata": {"ticket_id": "482"}}'

Statuts

queued running un statut terminal : succeeded, failed ou cancelled. Un run terminal ne change plus jamais d'état.

Un run qui appelle un outil client passe de running à requires_action : il attend les résultats que vous envoyez à POST /v1/runs/{run}/tool_outputs, puis repasse en queued et running. Il peut le faire plusieurs fois. Tant qu'il attend, required_action décrit les appels à exécuter ({"type": "submit_tool_outputs", "tool_calls": [{"id", "name", "arguments"}]}) ; il vaut null sinon. Sans résultats après 10 minutes, le run échoue en tool_outputs_timeout.

Lire un run

GET /v1/runs/{run} renvoie le run dans sa forme complète, qu'il soit terminé ou non : un run interrompu (annulé, ou en échec en cours de route) garde tout ce qu'il avait déjà produit :

{
  "data": {
    "id": "run_01k6exampler000000000000",
    "agent": "agt_01k6examplea0000000000000",
    "model": "mdl_01k6examplem0000000000000",
    "status": "succeeded",
    "metadata": { "ticket_id": "482" },
    "output_schema": false,
    "output": {
      "json": null,
      "text": "Le ticket #482 porte sur un remboursement en attente depuis trois jours.",
      "files": [
        { "id": "file_01k6examplef00000000000", "name": "resume-482.pdf", "type": "application/pdf", "size": 48213, "url": "https://.../v1/files/file_.../content?signature=...", "expires_at": "2026-09-28T10:13:20+00:00" }
      ],
      "charts": []
    },
    "steps": [
      { "tool": "web_search", "label": "Web search", "status": "succeeded", "duration_ms": 842 }
    ],
    "usage": { "credits": 1.85, "prompt_tokens": 512, "completion_tokens": 128, "tool_calls": 1 },
    "warnings": [],
    "error": null,
    "created_at": "2026-09-21T10:13:20+00:00",
    "started_at": "2026-09-21T10:13:21+00:00",
    "finished_at": "2026-09-21T10:13:26+00:00"
  }
}

• output_schema : true si le run a un schéma de sortie (figé à sa création), false sinon.
• output.json : la réponse décodée, conforme à output_schema ; null sans schéma, tant que le run n'est pas fini ou s'il a échoué. output.text reste toujours renseigné, même avec un schéma, voir Sortie structurée.
• output.files : les documents produits (PDF, DOCX, XLSX, PPTX), avec une URL de téléchargement signée, valable 7 jours : sans clé API, elle peut être remise telle quelle à un utilisateur final.
• output.charts : les graphiques produits, en données structurées (categories, series, x_axis, y_axis) plutôt qu'en image.
• usage.credits : le coût du run en crédits (2 décimales). C'est une estimation tant que le run n'est pas terminé, puis le coût figé à sa fin ; il peut encore être affiné quelques minutes après la fin, quand le fournisseur du modèle corrige son coût. GET /v1/runs/{run} fait foi ; un webhook ou l'événement terminal du flux SSE porte la valeur connue au moment de l'envoi.
• error : null sauf sur un run failed, auquel cas {"code": "...", "message": "..."}. Un run peut ainsi se terminer failed avec le code model_unavailable : son modèle a quitté votre formule entre la création du run et son démarrage. La liste complète des codes et la conduite à tenir figurent dans Échec d'un run. Avec un schéma de sortie, un run peut aussi échouer en output_invalid, output_schema_rejected ou output_schema_unsupported.

Annuler

POST /v1/runs/{run}/cancel demande l'arrêt d'un run actif. Un run encore queued est annulé immédiatement ; un run running s'arrête en une seconde environ, y compris pendant que le modèle écrit : la réponse en cours est coupée et ce qu'il a déjà produit reste dans output (le texte de l'appel interrompu compris). L'appel interrompu est facturé pour ce qui a été envoyé et produit jusqu'à l'arrêt. Un run en requires_action (en attente des résultats d'un outil client) est annulé immédiatement lui aussi. Un run déjà terminal renvoie 409 run_not_active.

Bornes

• Durée : 600 secondes au plus par run. L'attente des résultats d'un outil client n'est pas décomptée (elle a son propre délai de 10 minutes).
• Tours : 30 aller-retours modèle/outil au plus.
• Sortie : 100 000 caractères de texte au plus, et 100 000 caractères par résultat d'outil.
• Runs simultanés : 5 au plus par organisation par défaut, limite propre à chaque organisation (fixée par sa formule ou ajustée pour elle) (429 concurrent_runs_exceeded au-delà, avec Retry-After). Seuls les runs queued et running comptent : un run en requires_action n'occupe pas de place. Voir Erreurs et limites.

Conservation

Le contenu d'un run (entrée, sortie, erreurs, metadata, webhook_url) est gardé 30 jours puis caviardé : le run garde son identifiant, son organisation, son agent, sa clé, son statut, son code d'erreur et son coût, ce qui sert au décompte de votre consommation, mais son contenu disparaît, et il n'est plus lisible par l'API : GET /v1/runs/{run} renvoie alors 404 resource_not_found. Les fichiers d'un run (produits ou envoyés en entrée) sont supprimés après 7 jours, indépendamment du caviardage du run lui-même.