Stream an execution

/v1/executions/{id}/stream

Events: status (first, then on change), progress (one per interior step record of the tasks named in task, polled every 250 ms), done (terminal, or the run paused for the user, or reattach: true after 5 min), error (the run vanished mid-stream, e.g. deleted: one event, then the stream closes). A : ping comment every 15 s. A re-attach replays the progress records. Interior records exist for runs started with progress watching (async, MCP, Studio, scheduler runs); a plain synchronous REST run writes none and streams status only.

Authorizations

Authorizationstringheaderrequired

Bearer token: Authorization: Bearer ozk_…. ozk_ platform API key (Authorization: Bearer ozk_…)

Path parameters

idstringrequired

Execution id (the x-execution-id of the run, or its engine id exec-…)

Query parameters

taskstring[]

Task ids whose progress records to follow (repeat the parameter, or comma-separate)

Maximum array length: 4

Response

Server-sent events

text/event-stream

invalid_task — more than 4 ids, or an id with other than letters, digits, . : _ -

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

unauthorized — missing, invalid or revoked ozk_ key

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

execution_not_found — no execution with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

execution_finished — the run is already terminal, nothing to steer or attach to

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

too_many_streams — a run takes at most 5 live streams at once; close one

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

upstream_error — a store failed; no detail is returned, retry shortly

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

import os import requests response = requests.get( "https://api.plungeai.com/v1/executions/{id}/stream", headers={"Authorization": f"Bearer {os.environ['PLUNGE_API_KEY']}"}, ) if not response.ok: raise SystemExit(f"{response.status_code} {response.headers.get('X-Error-Code')}") print(response.json())

import os import requests with requests.get( "https://api.plungeai.com/v1/executions/{id}/stream", headers={"Authorization": f"Bearer {os.environ['PLUNGE_API_KEY']}"}, stream=True, ) as response: if not response.ok: raise SystemExit(f"{response.status_code} {response.headers.get('X-Error-Code')}") for line in response.iter_lines(): if line == b"data: [DONE]": break if line: print(line.decode())

const response = await fetch('https://api.plungeai.com/v1/executions/{id}/stream', { method: 'GET', headers: { Authorization: `Bearer ${process.env.PLUNGE_API_KEY}`, }, }) if (!response.ok) throw new Error(`${response.status} ${response.headers.get('X-Error-Code')}`) const reader = response.body!.getReader() const decoder = new TextDecoder() let buffer = '' read: while (true) { const { done, value } = await reader.read() if (done) break buffer += decoder.decode(value, { stream: true }) const frames = buffer.split('\n\n') buffer = frames.pop() ?? '' for (const frame of frames) { if (frame.trim() === 'data: [DONE]') break read console.log(frame) } }

import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class Main { public static void main(String[] args) throws Exception { HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.plungeai.com/v1/executions/{id}/stream")) .header("Authorization", "Bearer " + System.getenv("PLUNGE_API_KEY")) .GET() .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() >= 400) { System.out.println(response.statusCode() + " " + response.headers().firstValue("X-Error-Code").orElse("")); return; } System.out.println(response.body()); } }

import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class Main { public static void main(String[] args) throws Exception { HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.plungeai.com/v1/executions/{id}/stream")) .header("Authorization", "Bearer " + System.getenv("PLUNGE_API_KEY")) .GET() .build(); HttpResponse<java.util.stream.Stream<String>> response = client.send(request, HttpResponse.BodyHandlers.ofLines()); if (response.statusCode() >= 400) { System.out.println(response.statusCode() + " " + response.headers().firstValue("X-Error-Code").orElse("")); return; } response.body().takeWhile(line -> !line.equals("data: [DONE]")).forEach(System.out::println); } }

Stream an execution

Authorizations

Path parameters

Query parameters

Response

Planned: TI-33

Planned: TI-34