Migrate to SmithDB-backed SDK methods

Context

In May 2026, we released SmithDB, a new observability database built for modern AI agents. SmithDB delivers industry-leading performance across every key observability workload, making core LangSmith experiences dramatically faster. New SDK methods are required to query your traces with SmithDB. This guide helps you migrate your codebase.

Deprecation and removal

Each SDK method and its underlying endpoint share the same deprecation date.

Deployment	Deprecation	Removal
All Cloud regions	End of July 2026	31 Jan 2027
Self-Hosted	`v0.16`	`v0.18`

For details on how LangSmith deprecates and removes API endpoints and SDK methods, see API and SDK deprecation policy.

Minimum SDK version

The new SDK methods are available starting at these SDK versions:

Language	Package	Minimum version
Python	`langsmith`	`>=0.10.15`
TypeScript	`langsmith`	`>=0.8.9`
Java	`langsmith-java`	`0.1.0-beta.22`
Go	`langsmith-go`	`v0.25.4`
CLI	`langsmith-cli`	`v0.2.44`

The LangSmith CLI queries the same SmithDB-backed endpoints and requires v0.2.44 or later.

About self-hosted

The new methods documented in this guide require >=0.16 self-hosted version, independent of the data store used.
The deprecated methods stop working once ClickHouse is disabled.
Where possible, the SDK raises a warning or error identifying the version to upgrade to, instead of failing without explanation.

Methods by area

The before and after change for each method is documented on the page for its area.

Query runs

list_runs and its query parameters, response fields, and examples.

Retrieve runs

Read a single run and build a run URL.

Traces

Query traces and list the runs inside a trace.

Threads

Query threads and list the traces inside a thread.

Dataset experiment runs

Query the runs attached to a dataset experiment.

Feedback and sharing

Annotation queues, public runs, and feedback creation.

Migrate with an AI agent

This guide is written to be fetched and applied directly by an AI coding agent. Copy the following prompt into your agent to migrate your codebase to the SmithDB-backed methods.

Migrate this codebase's LangSmith SDK usage to the new SmithDB-backed methods.

Fetch https://docs.langchain.com/langsmith/smithdb-sdk-migration.md first. It
carries the minimum SDK versions, deprecation dates, exception changes, and
discontinued methods that apply to every call site.

The before/after change for each method lives on a per-area page. Fetch the
ones this codebase actually uses:

- https://docs.langchain.com/langsmith/smithdb-sdk-migration-query-runs.md
- https://docs.langchain.com/langsmith/smithdb-sdk-migration-runs.md
- https://docs.langchain.com/langsmith/smithdb-sdk-migration-traces.md
- https://docs.langchain.com/langsmith/smithdb-sdk-migration-threads.md
- https://docs.langchain.com/langsmith/smithdb-sdk-migration-experiments.md
- https://docs.langchain.com/langsmith/smithdb-sdk-migration-feedback.md

Treat those pages together as the source of truth for what changed, including
which methods and parameters are affected, what replaces them, and deployment
support.

1. Check the installed LangSmith SDK version against the minimum version
   required for the SmithDB-backed methods per this guide, and upgrade the
   dependency if it does not meet that minimum.
2. Identify every call site in this codebase that uses a method the guide
   marks as migrated, in whichever language(s) this codebase uses.
3. For each call site, apply the corresponding before/after change from the
   area page for that method, including any added, removed, or renamed
   parameters.

If a call site or parameter is not covered by the guide, stop and ask rather
than guessing.

Exceptions

Python
TypeScript
Java
Go
cURL

The SmithDB-backed methods raise new exception classes instead of the legacy langsmith.utils exception classes.

Before (`langsmith.utils`)	After (`langsmith`)	Notes
`LangSmithError`	`LangsmithError`	Base exception class for the SDK; casing changed
`LangSmithAPIError`	`InternalServerError`	5xx
`LangSmithRequestTimeout`	`APITimeoutError`	Raised when a request times out
`LangSmithUserError`	(removed)	No direct equivalent. The 403 org-scoped-key case now raises `PermissionDeniedError`; client-side argument validation now raises a standard `ValueError` or `TypeError`
`LangSmithRateLimitError`	`RateLimitError`	429; unchanged name
`LangSmithAuthError`	`AuthenticationError`	401
`LangSmithNotFoundError`	`NotFoundError`	404; unchanged name
`LangSmithConflictError`	`ConflictError`	409; unchanged name
`LangSmithConnectionError`	`APIConnectionError`	Raised when the client cannot connect to the API
`LangSmithExceptionGroup`	(removed)	No equivalent
(not available)	`APIError`	New: base class for all API-related errors, with `message`, `request`, and `body` attributes
(not available)	`APIStatusError`	New: base class for all 4xx/5xx status errors
(not available)	`BadRequestError`	New: 400
(not available)	`PermissionDeniedError`	New: 403
(not available)	`UnprocessableEntityError`	New: 422
(not available)	`APIResponseValidationError`	New: raised when a response does not match the expected schema

The SmithDB-backed methods raise new exception classes instead of plain Error.

Before (plain `Error`)	After (`langsmith`)	Notes
(not available)	`LangsmithError`	base class for all SDK errors
(not available)	`InternalServerError`	5xx
(not available)	`APIConnectionTimeoutError`	Raised when a request times out
(not available)	`RateLimitError`	429
(not available)	`AuthenticationError`	401
(not available)	`NotFoundError`	404
(not available)	`ConflictError`	409
(not available)	`APIConnectionError`	Raised when the client cannot connect to the API
(not available)	`APIError`	base class for all API-related errors, with `status`, `headers`, and `error` properties
(not available)	`BadRequestError`	400
(not available)	`PermissionDeniedError`	403
(not available)	`UnprocessableEntityError`	422
(not available)	`APIUserAbortError`	Raised when a request is aborted via an `AbortController`

Discontinued

The following methods are discontinued. They call the retired /feedback/formulas endpoints, which return 410 Gone on composite-feedback v2 and are scheduled for removal on 2026-08-20. Composite scores are now managed as composite evaluators, which implement a composite score as a code evaluator plus a run rule. There is no SDK replacement.

Feedback formula methods

Python	TypeScript
`list_feedback_formulas`	NA
`get_feedback_formula_by_id`	NA
`create_feedback_formula`	NA
`update_feedback_formula`	NA
`delete_feedback_formula`	NA

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

Edit this page on GitHub or file an issue.

SmithDB SDK migration

LangSmith REST API

Migrate to SmithDB-backed SDK methods

Context

Deprecation and removal

Minimum SDK version

About self-hosted

Methods by area

Query runs

Retrieve runs

Traces

Threads

Dataset experiment runs

Feedback and sharing

Migrate with an AI agent

Exceptions

Discontinued

Feedback formula methods

​Context

​Deprecation and removal

​Minimum SDK version

​About self-hosted

​Methods by area

Query runs

Retrieve runs

Traces

Threads

Dataset experiment runs

Feedback and sharing

​Migrate with an AI agent

​Exceptions

​Discontinued

​Feedback formula methods

Context

Deprecation and removal

Minimum SDK version

About self-hosted

Methods by area

Migrate with an AI agent

Exceptions

Discontinued

Feedback formula methods