Sign in
Thread Runs

Create And Stream Run

Create a new run and stream its execution via SSE.

Returns a text/event-stream response with Server-Sent Events. Each event has a type field (e.g. values, updates, messages, metadata, end) and a JSON data payload.

Set on_disconnect to "continue" if the run should keep executing after the client disconnects (default is "cancel"). Use stream_mode to control which event types are emitted.

A periodic SSE keepalive comment is sent every KEEPALIVE_INTERVAL_SECS so idle proxies don't drop long-running silent nodes (e.g. agents holding an upstream WebSocket).

post/threads/{thread_id}/runs/stream

Path parameters

thread_idstring required

Request body

assistant_idstring required

Assistant to execute

inputobject nullable

Input data for the run. Optional when resuming from a checkpoint.

configobject nullable

Execution config

contextobject nullable

Execution context

checkpointobject nullable

Checkpoint configuration (e.g., {'checkpoint_id': '...', 'checkpoint_ns': ''})

streamboolean

Enable streaming response

on_disconnectstring nullable

Behavior on client disconnect: 'cancel' (default) or 'continue'.

on_completion'delete' | 'keep' nullable

Behavior after stateless run completes: 'delete' (default) removes the ephemeral thread, 'keep' preserves it.

multitask_strategystring nullable

Strategy for handling concurrent runs on same thread: 'reject', 'interrupt', 'rollback', or 'enqueue'.

commandobject nullable

Command for resuming interrupted runs with state updates or navigation

stream_subgraphsboolean nullable

Whether to include subgraph events in streaming. When True, includes events from all subgraphs. When False (default when None), excludes subgraph events. Defaults to False for backwards compatibility.

metadataobject nullable

Request metadata propagated to OTEL trace attributes (langfuse.trace.metadata.<key>). Keys must match [A-Za-z0-9_-]{1,64}. Values must be primitive (str, int, float, bool); string values are capped at 512 characters. Maximum 32 keys. Use this for filterable attributes (tenant, feature flag, environment, sub-agent type) rather than payload data.

Response

Server-Sent Events stream

{"stackTrail":"paths:/threads/{thread_id}/runs/stream:post:responses:200:content:application/json:schema","oasType":"schema","type":"unknown"}

Changes

Changed in 3 of the 53 revisions of this API.7

  • f2396b21b7b52See the full diff
    • ○

      the config request property default value {} was removed

      request-property-default-value-removed

    • ○

      the context request property default value {} was removed

      request-property-default-value-removed

  • 7c41348cb28f4See the full diff
    • ○

      api tag Thread Runs added

      api-tag-added

    • ○

      api tag Runs removed

      api-tag-removed

    • ○

      added the media type text/event-stream for the response with the status 200

      response-media-type-added

    • ○

      added the non-success response with the status 409

      response-non-success-status-added

  • 792bbf085a211See the full diff
    • ○

      added the new optional request property on_completion

      new-optional-request-property