Skip to main content
By default, LangSmith assigns a random ID to each run. You can override this with a custom ID when you need to:
  • Know the run ID ahead of time (e.g., to attach feedback immediately after a run).
  • Correlate LangSmith runs with IDs from an external system.
  • Make runs idempotent by reusing a deterministic ID.
We recommend using UUID v7 custom run IDs. UUIDv7 embeds a timestamp, which preserves correct time-ordering of runs in a trace. Passing a non-UUIDv7 ID currently emits a warning, and will be required by a future version.The LangSmith SDK exports a uuid7 helper (Python v0.4.43+, JS v0.3.80+):
  • Python: from langsmith import uuid7
  • JS/TS: import { uuid7 } from 'langsmith'
Any UUID v7 string is accepted. You can pass one generated by the LangSmith SDK helpers, or your own if your system already uses UUID v7 identifiers.

​
Use @traceable

Pass run_id inside langsmith_extra when calling a @traceable function:
Python
from langsmith import traceable, uuid7

@traceable
def my_pipeline(question: str) -> str:
    return "answer"

run_id = uuid7()
my_pipeline("What is the capital of France?", langsmith_extra={"run_id": run_id})

# run_id can now be used to attach feedback, query the run, etc.

​
Use the trace context manager

Pass run_id directly to the trace context manager constructor to set the ID for that traced block:
Python
from langsmith import trace, uuid7

run_id = uuid7()

with trace("my-pipeline", run_id=run_id) as run:
    result = "answer"
    run.end(outputs={"result": result})

# run_id can now be used to attach feedback, query the run, etc.
Edit this page on GitHub or file an issue.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.