Ausführungen · Ephemeral Docs

Starten Sie Ausführungen, verfolgen Sie sie und lesen Sie ihre Ergebnisse. Jeder Endpunkt auf dieser Seite funktioniert mit member- und admin-Schlüsseln. Lebenszyklus und Limits beschreibt Ausführungen.

Eine Ausführung starten

POST/v1/runs

Erstellt eine Ausführung und stellt sie in die Warteschlange. Senden Sie entweder einen prompt oder den Namen eines gespeicherten workflow.

Body

promptstring

Die Aufgabe. Erforderlich, sofern nicht workflow gesetzt ist; mit einem Workflow ersetzt er den gespeicherten Prompt. Bis zu 128 KiB.

inputany JSON

Daten für die Aufgabe, die dem Agenten als JSON übergeben werden. Bis zu 1 MiB.

workflowstring

Name eines gespeicherten Workflows. Andere Definitionsfelder, die Sie senden, überschreiben die gespeicherten.

modelstring

Modell-ID. Standardmäßig default_model aus GET /v1/models.

filesarray

Bis zu 32 Einträge, jeweils {"file": "<id or name>", "path": "..."} oder {"path": "...", "content": "..."}. Siehe Dateien.

connectionsobject

Bis zu 16 Verbindungen, nach dem Namen geordnet, den der Agent sieht. Jede ist {"ref": "<saved name>"} mit optionalen allowed_methods oder allowed_tools oder eine Inline-Definition. Siehe Verbindungen.

descriptionstring

Was die Ausführung tut, für Personen und Agents. Bis zu 500 Zeichen. Bei einer Inline-Ausführung harmlos; mit einem Workflow ersetzt sie die gespeicherte Beschreibung.

input_schemaobject

Ein JSON Schema, dem input entsprechen muss; bei einer Abweichung antwortet 400 mit Pfad und Grund, etwa input.city: required. Mit einem Workflow ersetzt es das gespeicherte Schema. Siehe Eingabe und Ausgabe beschreiben.

output_schemaobject

Ein JSON Schema, dem die Ausgabe der Ausführung entsprechen muss; bei einer Abweichung endet die Ausführung mit failed. Mit einem Workflow ersetzt es das gespeicherte Schema. Siehe Eingabe und Ausgabe beschreiben.

timeout_secondsinteger

1 bis 3600. Standard 300.

shellboolean

Erlaubt dem Agenten, Shell-Befehle auszuführen und Dateien in seinem Arbeitsverzeichnis zu schreiben. Standard true.

webboolean | object

Erlaubt dem Agenten, über Ephemeral Seiten abzurufen, öffentliche APIs aufzurufen und zu suchen. true oder { "allow": [domains], "search": false }, um es einzuschränken. Standardmäßig aus. Siehe Webzugriff.

zero_data_retentionboolean

Zeichnet nichts vom Inhalt der Ausführung auf: keine gespeicherten Ereignisse, keine Definition, und die Ausgabe wird nur einmal geliefert. Gehostete Ausführungen kosten mehr. Siehe Null-Datenspeicherung. Standard ist false.

max_cost_microsinteger

Budget, 1 bis 100.000.000. Standardmäßig default_max_cost_micros aus GET /v1/me. Beim gehosteten Dienst muss es die Rechenzeitgebühr für das volle Zeitlimit abdecken. Siehe Budgets.

callbackobject

{"url": "...", "secret": "..."} für eine signierte Anfrage, wenn die Ausführung endet. Siehe Callbacks.

Header

Idempotency-Keystring

Optional, bis zu 200 Zeichen. Ein wiederholter Schlüssel liefert die bestehende Ausführung mit 200 zurück.

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
  }'

Die Antwort lautet 202 Accepted mit dem neuen Ausführungsobjekt. Eine Anfrage, die die Validierung nicht besteht, liefert 400 und erstellt nichts. Beim gehosteten Dienst bedeutet 402, dass Ihr verfügbares Guthaben das Budget nicht deckt.

Das Ausführungsobjekt

idstring

Ausführungs-ID, etwa run_4abb0f420c6623a12d2889610eb67284.

statusstring

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

outputstring

Die endgültige Antwort des Agenten. Fehlt, bis es eine gibt. Bis zu 1 MiB; eine längere Antwort wird dort abgeschnitten, und ein output_truncated-Ereignis weist darauf hin.

errorstring

Warum die Ausführung nicht erfolgreich war. Fehlt, wenn leer.

created_attimestamp

Wann die Ausführung erstellt wurde.

started_attimestamp

Wann sie die Warteschlange verlassen hat. Fehlt davor.

finished_attimestamp

Wann sie einen finalen Status erreicht hat. Fehlt davor.

max_cost_microsinteger

Das Budget der Ausführung.

cost_microsinteger

Bisherige Kosten. Vorläufig, bis billing_pending bei einer beendeten Ausführung false ist. Fehlt, wenn null.

billing_pendingboolean

Ob die Kosten noch abgerechnet werden müssen.

schedule_idstring

Der Zeitplan, der die Ausführung gestartet hat, falls einer es getan hat.

zero_data_retentionboolean

true bei einer Ausführung mit Null-Datenspeicherung.

surcharge_percentinteger

Der Aufschlagssatz bei Ausführungen mit Null-Datenspeicherung im gehosteten Dienst.

surcharge_microsinteger

Der Teil von cost_micros, den der Aufschlag für Null-Datenspeicherung ausmacht. Entfällt bei null.

output_availableboolean

Nur bei Null-Datenspeicherung: ob die Ausgabe noch zum Abruf vorgehalten wird.

output_expires_attimestamp

Nur bei Null-Datenspeicherung: wann eine vorgehaltene Ausgabe gelöscht wird, wenn sie niemand gelesen hat.

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
}

Ausführungen auflisten

GET/v1/runs

Liefert Ausführungen, die neuesten zuerst.

Query

limitinteger

1 bis 100. Aktiviert paginierte Antworten.

cursorstring

Der next_cursor der vorherigen Seite.

statusstring

Liefert nur Ausführungen mit diesem Status.

schedulestring

Liefert nur Ausführungen, die dieser Zeitplan gestartet hat.

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

Ohne limit oder cursor ist die Antwort ein einfaches Array der 100 neuesten passenden Ausführungen. Siehe Paginierung.

Eine Ausführung abrufen

GET/v1/runs/{id}

Liefert das Ausführungsobjekt. Fragen Sie dies ab, bis der Status final ist, oder nutzen Sie Ereignisse oder einen Callback.

Ereignisse streamen

GET/v1/runs/{id}/events

Ein Server-Sent-Events-Stream. Er gibt jedes aufgezeichnete Ereignis wieder und sendet dann neue, sobald sie eintreten. Ist die Ausführung final, sendet er done mit dem Ausführungsobjekt und schließt.

Header

Last-Event-IDinteger

Nach dieser Ereignis-ID fortsetzen, zum Beispiel beim erneuten Verbinden nach einer abgebrochenen Verbindung.

Text

: 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", …}

Das data jeder Nachricht ist ein Ereignisobjekt mit id, type, data und created_at, außer bei done, das das Ausführungsobjekt enthält. Zeilen, die mit einem Doppelpunkt beginnen, sind Kommentare; alle 15 Sekunden wird ein Heartbeat-Kommentar gesendet. Die Ereignistypen sind unter Ereignistypen aufgeführt. Das Trennen der Verbindung bricht die Ausführung nicht ab.

Terminal

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

Eine Ausführung abbrechen

POST/v1/runs/{id}/cancel

Bricht eine Ausführung im Status reserving, queued, starting oder running ab und liefert das Ausführungsobjekt. Eine bereits beendete Ausführung wird unverändert zurückgegeben.

Der Abbruch stoppt den Worker. Er macht nichts rückgängig, was der Agent bereits über eine Verbindung getan hat.

Eine Ausführungsdefinition lesen

GET/v1/runs/{id}/definition

Liefert die Definition, die die Ausführung tatsächlich verwendet hat, aufbereitet zur Prüfung vor einer erneuten Ausführung.

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 ist die aufgelöste Definition. Dateinamen werden durch die verwendeten IDs ersetzt, und die gespeicherten Felder eines Workflows werden eingesetzt. Workflow-Name und Callback fehlen. Gespeicherte Verbindungen behalten nur ihren Verweis und ihre Zulassungslisten. Inline-Verbindungen verlieren ihre Zugangsdaten und alle Geheimnisse in ihrer URL.

requires_credentials listet Inline-Verbindungen auf, bei denen Zugangsdaten oder die ursprüngliche URL wiederhergestellt werden müssen. Um sie erneut auszuführen, fügen Sie diese wieder hinzu, wählen Sie ein neues max_cost_micros und senden Sie die Anfrage an POST /v1/runs. Verweise auf gespeicherte Verbindungen werden dabei erneut aufgelöst, und die Anfrage schlägt fehl, wenn eine referenzierte Datei oder Verbindung gelöscht wurde.

Die Definition enthält Ihren Prompt, Ihre Eingabe und die Inline-Dateiinhalte wie gesendet. Legen Sie darin keine Geheimnisse ab.

Ausführungen mit Null-Datenspeicherung

Eine Ausführung mit zero_data_retention liefert ihre Ausgabe einmal. Das erste GET /v1/runs/{id} nach dem Ende enthält output und löscht sie; spätere Lesezugriffe lassen sie weg und melden output_available: false. Hat die Ausführung einen Callback, liefert dieser die Ausgabe, und GET lässt sie bis dahin bestehen. Eine nicht gelieferte Ausgabe wird spätestens nach einer Stunde gelöscht.

Der Ereignisstrom funktioniert, solange die Ausführung läuft, und noch wenige Minuten danach. GET /v1/runs/{id}/definition liefert 410, und Ausführungslisten enthalten nie eine Ausgabe. Im gehosteten Dienst enthält cost_micros den Aufschlag, und das Budget muss ihn abdecken.