Specify a custom run ID

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.

Python
TypeScript

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.

Use `traceable`

Pass id in the config object passed to 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.

Attach user feedback: common use case for pre-specifying a run ID.
Access the current run (span) within a traced function: read the auto-assigned ID from inside a trace.
Trace with the LangSmith API: low-level API approach for specifying run IDs.
Trace Vercel AI SDK applications: specifying a custom run ID with wrapAISDK.

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Tracing setup

Configuration & troubleshooting

Viewing & managing traces

Automations

Feedback & evaluation

Monitoring & alerting

Data type reference

Use `@traceable`

Use the `trace` context manager

Use `traceable`

​Use @traceable

​Use the trace context manager

​Use traceable

​Related

Use `@traceable`

Use the `trace` context manager

Use `traceable`

Related