Stream Run (SSE)

curl --request GET \
  --url https://app.uselamina.ai/v1/runs/{runId}/stream \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://app.uselamina.ai/v1/runs/{runId}/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.uselamina.ai/v1/runs/{runId}/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.uselamina.ai/v1/runs/{runId}/stream"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.uselamina.ai/v1/runs/{runId}/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

"event: progress\ndata: {\"runId\":\"fc32ae7d-...\",\"status\":\"running\",\"outputs\":[...]}\n\nevent: ping\ndata: 1713456789000\n\nevent: complete\ndata: {\"runId\":\"fc32ae7d-...\",\"status\":\"completed\",\"outputs\":[{\"id\":\"...\",\"type\":\"image\",\"value\":\"https://...\",\"status\":\"completed\"}]}\n"

{
  "error": "Invalid API key"
}

{
  "error": "App not found"
}

"Too many requests from this IP, please try again in a minute"

Track

Stream Run

Opens a Server-Sent Events (SSE) stream for real-time execution progress. This is an alternative to polling GET /v1/runs/{runId} — use whichever fits your architecture better.

Connection: The stream uses standard SSE (text/event-stream). Most HTTP clients and all modern browsers support this natively.

Event types:

Event	When	Data payload
`progress`	Execution status changes (e.g. `queued` -> `running`)	Full `ExecutionStatus` object
`complete`	All outputs are ready	Full `ExecutionStatus` with final values
`error`	Execution failed or was cancelled	Full `ExecutionStatus` with error details
`timeout`	Stream exceeded 10-minute limit	`{ "message": "Stream timeout after 10 minutes" }`
`ping`	Keepalive every ~15 seconds	Unix timestamp

Terminal behavior:

If the execution is already in a terminal state (completed, failed, cancelled) when you connect, the stream sends a single complete or error event and closes.
Otherwise, the stream stays open and polls internally every 2 seconds.
The stream automatically closes after 10 minutes with a timeout event.

Agent usage pattern:

const es = new EventSource('/v1/runs/{id}/stream', {
  headers: { 'x-api-key': 'lma_...' }
});
es.addEventListener('complete', (e) => {
  const result = JSON.parse(e.data);
  // result.outputs contains final values
  es.close();
});
es.addEventListener('error', (e) => {
  const result = JSON.parse(e.data);
  console.error(result.errorMessage);
  es.close();
});

GET

runs

{runId}

stream

Stream Run (SSE)

curl --request GET \
  --url https://app.uselamina.ai/v1/runs/{runId}/stream \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://app.uselamina.ai/v1/runs/{runId}/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.uselamina.ai/v1/runs/{runId}/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.uselamina.ai/v1/runs/{runId}/stream"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.uselamina.ai/v1/runs/{runId}/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

"event: progress\ndata: {\"runId\":\"fc32ae7d-...\",\"status\":\"running\",\"outputs\":[...]}\n\nevent: ping\ndata: 1713456789000\n\nevent: complete\ndata: {\"runId\":\"fc32ae7d-...\",\"status\":\"completed\",\"outputs\":[{\"id\":\"...\",\"type\":\"image\",\"value\":\"https://...\",\"status\":\"completed\"}]}\n"

{
  "error": "Invalid API key"
}

{
  "error": "App not found"
}

"Too many requests from this IP, please try again in a minute"

Opens a Server-Sent Events (SSE) stream for real-time execution progress. Use this instead of polling when you need instant updates — for example, to drive a progress bar, stream partial outputs to a UI, or feed status changes into an agent loop. The connection stays open until the execution reaches completed or failed. Each SSE event contains the current execution state, including per-node output status. The final event carries the full completed (or failed) execution payload, after which the server closes the stream.

Authorizations

x-api-key

string

header

required

Workspace API key. Prefix: lma_. Example: lma_abc123...

Path Parameters

runId

string<uuid>

required

The run ID returned from the Run App or Content Create endpoint

Response

SSE event stream. Each event is a data: line followed by two newlines.

The response is of type string.

Overview

Install

Concepts

API Reference

Guides

Stream Run

Authorizations

Path Parameters

Response