Results and Streaming API

Last validated: 2026-05-14

This page explains how to retrieve thread outputs, step details, and large payloads safely.

1) Results RPC Matrix

2) GetThreadResult (Unary)

Request fields:

• thread_id (required)
• step_path (optional): exact hierarchical step path like 1.0.2
• output_only (optional): skip step summaries/details
• metadata_only (optional): return metadata without output payload

Response fields to monitor:

• output_data (bytes)
• output_total_bytes
• output_truncated
• steps[] summaries
• step_details[] when step_path is provided
• yielded_values[], total_yielded, yields_truncated

Current runtime notes:

• Unary practical cap is around 4 MB for output payloads.
• step_path filtering is exact-match.
• Inline yielded values are capped.

Use cases:

• Fast polling for compact outputs.
• Summary dashboards with metadata_only=true.
• Single-step diagnosis with step_path.

3) StreamThreadResult (Output Chunks)

Request fields:

• thread_id (required)
• max_chunk_bytes (optional): default 2 MB, clamped to 64 KB..16 MB

Stream shape:

• First chunk is metadata (ThreadOutputMeta)
• Subsequent chunks are output bytes (OutputChunk)
• chunk_index and is_final identify ordering/completion

Use cases:

• Download very large result payloads reliably.
• Avoid unary response size limits.

4) StreamStepResult (Step Data Chunks)

Request fields:

• thread_id (required)
• step_path (optional): stream one step or all steps
• max_chunk_bytes (optional)

Stream shape:

• meta (StepResultMeta) with step summaries
• per-step records (StepDetail)
• extra chunk records (StepDataChunk) for large step input/output fields

Current runtime note:

• Chunked StepDataChunk.field currently emits output path in practice.

Use cases:

• Deep incident debugging with large step payloads.
• Offline export of step-level telemetry.

5) Example Calls

gRPC unary, then stream fallback

# Unary first
grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"thread_id":"thr_abc123"}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/GetThreadResult
 
# Stream output if truncated
grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"thread_id":"thr_abc123","max_chunk_bytes":1048576}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/StreamThreadResult

gRPC single-step details

grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"thread_id":"thr_abc123","step_path":"1.2.0"}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/StreamStepResult

HTTP contract example (gateway deployment)

curl -sS "https://api.dev.dodil.io:443/v1/scriptum/threads/thr_abc123/result" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID"

6) Retrieval Strategy (Recommended)

1. Call GetThreadResult after terminal status.
2. If output_truncated=true, switch to StreamThreadResult.
3. If step output is truncated, switch to StreamStepResult.
4. Persist output and step payloads as files for reproducible incident analysis.

7) Known Gaps and Safe Workarounds

• ListArtifacts currently returns UNIMPLEMENTED: store and manage output artifacts in your own sink when needed.
• Contract comments mention StreamYieldedValues, but no such RPC exists in the service.
• For high-volume outputs, prefer chunk sizes that match your client memory and network constraints.