Skip to main content

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. 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: 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

Search the runs in a project: filters, field projection, sorting, and pagination. The largest surface area in the migration.

Retrieve runs

Fetch one run by ID, load its child runs, and build the URL of a run in the LangSmith UI.

Traces

Query the traces in a project, read their token and cost aggregates, and list the runs that belong to one trace.

Threads

Query the threads in a project and list the traces (turns) that belong to one thread.

Dataset experiment runs

Query the runs recorded by an experiment on a dataset, including pagination and sorting by feedback score.

Feedback and sharing

Create feedback on a run, add runs to an annotation queue, and share, unshare, or read publicly shared runs.

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.

Exceptions

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

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