Exécutions · Documentation Ephemeral

Lancez des exécutions, suivez-les et lisez leurs résultats. Tous les endpoints de cette page fonctionnent avec les clés member et admin. Voir exécutions pour le cycle de vie et les limites.

Lancer une exécution

POST/v1/runs

Crée une exécution et la met en file d'attente. Envoyez soit un prompt, soit le nom d'un workflow enregistré.

Corps

promptstring

La tâche. Obligatoire sauf si workflow est défini ; avec un workflow, il remplace le prompt enregistré. 128 Kio au maximum.

inputany JSON

Données de la tâche, transmises à l'agent en JSON. 1 Mio au maximum.

workflowstring

Nom d'un workflow enregistré. Les autres champs de définition que vous envoyez remplacent ceux qui sont enregistrés.

modelstring

ID du modèle. Par défaut, default_model de GET /v1/models.

filesarray

32 entrées au maximum, chacune de la forme {"file": "<id or name>", "path": "..."} ou {"path": "...", "content": "..."}. Voir fichiers.

connectionsobject

16 connexions au maximum, indexées par le nom que voit l'agent. Chacune est soit {"ref": "<saved name>"} avec allowed_methods ou allowed_tools en option, soit une définition en ligne. Voir connexions.

descriptionstring

Ce que fait l'exécution, pour les personnes et les agents. 500 caractères au maximum. Sans effet sur une exécution en ligne ; avec un workflow, elle remplace la description enregistrée.

input_schemaobject

Un JSON Schema auquel input doit correspondre ; en cas d'écart, la réponse est 400 avec le chemin et la raison, par exemple input.city: required. Avec un workflow, il remplace le schéma enregistré. Voir décrire l'entrée et la sortie.

output_schemaobject

Un JSON Schema auquel la sortie de l'exécution doit correspondre ; en cas d'écart, l'exécution se termine en failed. Avec un workflow, il remplace le schéma enregistré. Voir décrire l'entrée et la sortie.

timeout_secondsinteger

De 1 à 3600. 300 par défaut.

shellboolean

Permet à l'agent d'exécuter des commandes shell et d'écrire des fichiers dans son répertoire de travail. true par défaut.

webboolean | object

Permet à l'agent de récupérer des pages, d'appeler des API publiques et de faire des recherches via Ephemeral. true, ou { "allow": [domains], "search": false } pour le limiter. Désactivé par défaut. Voir accès web.

zero_data_retentionboolean

N'enregistre rien du contenu de l'exécution : ni événements conservés, ni définition, et la sortie n'est renvoyée qu'une fois. Les exécutions hébergées coûtent plus cher. Voir rétention zéro des données. Par défaut : false.

max_cost_microsinteger

Budget, de 1 à 100 000 000. Par défaut, default_max_cost_micros de GET /v1/me. Sur le service hébergé, il doit couvrir le coût de calcul pour le délai d'expiration complet. Voir budgets.

callbackobject

{"url": "...", "secret": "..."} pour une requête signée à la fin de l'exécution. Voir callbacks.

En-têtes

Idempotency-Keystring

Facultatif, 200 caractères au maximum. Une clé répétée renvoie l'exécution existante avec 200.

Terminal

curl $EPHEMERAL_URL/v1/runs \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d0f3c1e-6a52-4b8e-9f21-0c4d5e6a7b89" \
  -d '{
    "workflow": "investigate-payment",
    "input": { "payment_id": "pay_123" },
    "max_cost_micros": 500000
  }'

La réponse est 202 Accepted avec le nouvel objet d'exécution. Une requête qui échoue à la validation renvoie 400 et ne crée rien. Sur le service hébergé, 402 signifie que vos crédits disponibles ne couvrent pas le budget.

L'objet d'exécution

idstring

ID de l'exécution, par exemple run_4abb0f420c6623a12d2889610eb67284.

statusstring

reserving, queued, starting, running, succeeded, failed, cancelled, timed_out ou interrupted.

outputstring

La réponse finale de l'agent. Absente tant qu'il n'y en a pas. 1 Mio au maximum ; une réponse plus longue est coupée à cette limite et un événement output_truncated l'indique.

errorstring

Pourquoi l'exécution n'a pas réussi. Absent lorsque vide.

created_attimestamp

Date de création de l'exécution.

started_attimestamp

Date de sortie de la file d'attente. Absente avant.

finished_attimestamp

Date d'arrivée à un statut final. Absente avant.

max_cost_microsinteger

Le budget de l'exécution.

cost_microsinteger

Coût à ce jour. Provisoire tant que billing_pending n'est pas false sur une exécution terminée. Absent lorsqu'il vaut zéro.

billing_pendingboolean

Indique si le coût doit encore être réglé.

schedule_idstring

La planification qui a lancé l'exécution, le cas échéant.

zero_data_retentionboolean

true pour une exécution à rétention zéro.

surcharge_percentinteger

Le taux du supplément, pour les exécutions à rétention zéro sur le service hébergé.

surcharge_microsinteger

La part de cost_micros ajoutée par le supplément de rétention zéro. Omise lorsqu'elle est nulle.

output_availableboolean

Exécutions à rétention zéro uniquement : indique si la sortie est encore conservée pour être récupérée.

output_expires_attimestamp

Exécutions à rétention zéro uniquement : date à laquelle une sortie conservée est supprimée si personne ne l'a lue.

JSON

{
  "id": "run_4abb0f420c6623a12d2889610eb67284",
  "status": "succeeded",
  "output": "The card issuer declined pay_123 for insufficient funds. The processor had no incidents. Ask the customer to retry or use another card.",
  "created_at": "2026-10-03T09:14:05.118Z",
  "started_at": "2026-10-03T09:14:05.402Z",
  "finished_at": "2026-10-03T09:14:41.877Z",
  "max_cost_micros": 500000,
  "cost_micros": 14390,
  "billing_pending": false
}

Lister les exécutions

GET/v1/runs

Renvoie les exécutions, les plus récentes d'abord.

Requête

limitinteger

De 1 à 100. Active les réponses paginées.

cursorstring

Le next_cursor de la page précédente.

statusstring

Ne renvoie que les exécutions ayant ce statut.

schedulestring

Ne renvoie que les exécutions lancées par cette planification.

GET /v1/runs?limit=2&status=failed

{
  "items": [
    { "id": "run_91c0…", "status": "failed", "error": "Worker failed; inspect run events. External actions may have completed.", "created_at": "2026-10-03T08:51:12.004Z", "max_cost_micros": 500000, "cost_micros": 61200, "billing_pending": false },
    { "id": "run_3fd2…", "status": "failed", "error": "Credit reservation failed", "created_at": "2026-10-02T17:20:44.390Z", "max_cost_micros": 500000, "billing_pending": false }
  ],
  "next_cursor": "eyJvIjoib3JnXzVlMmIi…"
}

Sans limit ni cursor, la réponse est un simple tableau des 100 exécutions correspondantes les plus récentes. Voir pagination.

Lire une exécution

GET/v1/runs/{id}

Renvoie l'objet d'exécution. Interrogez-le jusqu'à ce que le statut soit final, ou utilisez les événements ou un callback.

Suivre les événements en direct

GET/v1/runs/{id}/events

Un flux d'événements serveur. Il rejoue tous les événements enregistrés, puis envoie les nouveaux au fur et à mesure. Lorsque l'exécution est finale, il envoie done avec l'objet d'exécution et se ferme.

En-têtes

Last-Event-IDinteger

Reprend après cet ID d'événement, par exemple lors d'une reconnexion après une coupure.

Texte

: connected

id: 88412
event: status
data: {"id":88412,"type":"status","data":{"status":"running"},"created_at":"2026-10-03T09:14:05.431Z"}

id: 88415
event: worker_started
data: {"id":88415,"type":"worker_started","data":{"runtime":"pi","mode":"pi","shell":false},"created_at":"2026-10-03T09:14:07.906Z"}

id: 88419
event: tool_start
data: {"id":88419,"type":"tool_start","data":{"tool":"http_0","id":"call_1","arguments":{"method":"GET","path":"/payments/pay_123"}},"created_at":"2026-10-03T09:14:10.215Z"}

id: 88431
event: result
data: {"id":88431,"type":"result","data":{"output":"The card issuer declined pay_123 for insufficient funds."},"created_at":"2026-10-03T09:14:41.702Z"}

event: done
data: {"id":"run_4abb0f420c6623a12d2889610eb67284","status":"succeeded", …}

Le champ data de chaque message est un objet d'événement avec id, type, data et created_at, sauf done, qui contient l'objet d'exécution. Les lignes commençant par deux-points sont des commentaires ; un commentaire de battement de cœur est envoyé toutes les 15 secondes. Les types d'événements sont listés sous types d'événements. Se déconnecter n'annule pas l'exécution.

Terminal

curl -N $EPHEMERAL_URL/v1/runs/run_4abb0f420c6623a12d2889610eb67284/events \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY"

Annuler une exécution

POST/v1/runs/{id}/cancel

Annule une exécution en statut reserving, queued, starting ou running et renvoie l'objet d'exécution. Une exécution déjà terminée est renvoyée telle quelle.

L'annulation arrête le worker. Elle n'annule rien de ce que l'agent a déjà fait via une connexion.

Lire la définition d'une exécution

GET/v1/runs/{id}/definition

Renvoie la définition réellement utilisée par l'exécution, préparée pour être relue avant de la relancer.

JSON

{
  "request": {
    "prompt": "Find out why this payment failed. Follow the playbook.",
    "model": "anthropic/claude-haiku-5.5",
    "files": [{ "file": "file_9c41d2a07be35f1e8a6c0d4b9e2f7a13", "path": "playbook.md" }],
    "connections": {
      "payments": { "ref": "payments-api", "allowed_methods": ["GET"] },
      "crm": { "type": "http", "url": "https://api.example.com", "allowed_methods": ["GET"] }
    },
    "timeout_seconds": 120,
    "shell": false,
    "max_cost_micros": 500000,
    "input": { "payment_id": "pay_123" }
  },
  "requires_credentials": ["crm"]
}

request est la définition résolue. Les noms de fichiers sont remplacés par les ID utilisés, et les champs enregistrés d'un workflow sont renseignés. Le nom du workflow et le callback sont omis. Les connexions enregistrées ne conservent que leur référence et leurs listes d'autorisation. Les connexions en ligne perdent leurs identifiants et les secrets présents dans leur URL.

requires_credentials liste les connexions en ligne dont il faut rétablir les identifiants ou l'URL d'origine. Pour relancer l'exécution, remettez-les, choisissez un nouveau max_cost_micros et envoyez la requête à POST /v1/runs. Les références de connexions enregistrées sont alors résolues de nouveau, et la requête échoue si un fichier ou une connexion référencé a été supprimé.

La définition conserve votre prompt, votre entrée et le contenu des fichiers en ligne tels qu'envoyés. N'y placez pas de secrets.

Exécutions à rétention zéro

Une exécution avec zero_data_retention renvoie sa sortie une seule fois. Le premier GET /v1/runs/{id} après la fin inclut output et la supprime ; les lectures suivantes l'omettent et indiquent output_available: false. Si l'exécution a un callback, il livre la sortie et GET la laisse en place d'ici là. Une sortie non livrée est supprimée au plus tard après une heure.

Le flux d'événements fonctionne pendant l'exécution et quelques minutes après. GET /v1/runs/{id}/definition renvoie 410, et les listes d'exécutions n'incluent jamais la sortie. Sur le service hébergé, cost_micros inclut le supplément et le budget doit le couvrir.