Skip to main content
References are key/value identifiers—such as an order ID, customer ID or support ticket—that let you find a thread using names already used by your systems.

Adding References

Querying by Reference

Ordinary business refs can match multiple threads; they do not enforce uniqueness or merge threads. Use the SDK’s thread(threadKey, options?) entry point to create or resume one thread with a unique application key. OpenTelemetry uses threadify.thread_key for that same identity. JavaScript lookups accept exactly one ref pair, with filters in an optional second argument. See Getting Threads for pagination, return values, and examples.

Next Steps

Sub-steps

Break down complex operations

Getting Threads

Query workflow data

Run correlation is different

threadify.thread_key identifies one logical run. OTLP ingestion uses it ahead of workflow.run_id, then falls back to a trace ID. Several traces with the same thread key can contribute to one thread. Use a unique value for each intended run; put a customer ID in business refs when a customer has multiple runs. The SDK’s create or resume API accepts the same key, so instrumentation does not need to store the internal threadId. This is separate from the Engine’s internal thread UUID and from ordinary refs such as customer_id. Correlation conflicts are rejected; existing threads are not retroactively merged. See OpenTelemetry for configuration.