Specify a custom run ID ↗
noOriginal Documentation
Documentation Index#
Fetch the complete documentation index at: https://docs.langchain.com/llms.txt Use this file to discover all available pages before exploring further.
How to specify a custom run ID when tracing with LangSmith.
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:
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](https://reference.langchain.com/python/langsmith/run_helpers/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.
```
<span class="tab-end"></span>
<span class="tab-start" data-tab-title="TypeScript"></span>
### Use `traceable`
Pass `id` in the config object passed to [`traceable`](https://reference.langchain.com/javascript/langsmith/traceable/traceable):
```typescript
import { traceable } from "langsmith/traceable";
import { uuid7 } from "langsmith";
const runId = uuid7();
const myPipeline = traceable(
async (question: string) => {
return "answer";
},
{ name: "my-pipeline", id: runId }
);
await myPipeline("What is the capital of France?");
// runId can now be used to attach feedback, query the run, etc.
```
<span class="tab-end"></span>
<span class="tab-group-end"></span>
## Related
* [Attach user feedback](/langsmith/attach-user-feedback): common use case for pre-specifying a run ID.
* [Access the current run (span) within a traced function](/langsmith/access-current-span): read the auto-assigned ID from inside a trace.
* [Trace with the LangSmith API](/langsmith/trace-with-api): low-level API approach for specifying run IDs.
* [Trace Vercel AI SDK applications](/langsmith/trace-with-vercel-ai-sdk): specifying a custom run ID with `wrapAISDK`.
***
<span class="callout-start" data-callout-type="note"></span>
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/custom-run-id.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
<span class="callout-end"></span>
<span class="callout-start" data-callout-type="note"></span>
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
<span class="callout-end"></span>