Client

The Client class is the primary interface for interacting with the LangSmith API. It handles tracing, datasets, experiments, feedback, and all other LangSmith features.

Constructor

import { Client } from "langsmith";

const client = new Client({
  apiKey: process.env.LANGSMITH_API_KEY,
  apiUrl: "https://api.smith.langchain.com",
});

config

ClientConfig

Configuration options for the client

ClientConfig properties

apiKey

string

Your LangSmith API key. Defaults to LANGSMITH_API_KEY environment variable.

apiUrl

string

The LangSmith API URL. Defaults to https://api.smith.langchain.com.

webUrl

string

The LangSmith web UI URL. Auto-detected from apiUrl if not provided.

workspaceId

string

The workspace ID. Required for org-scoped API keys.

timeout_ms

number

default:"90000"

Request timeout in milliseconds.

hideInputs

boolean | ((inputs: KVMap) => KVMap | Promise<KVMap>)

Whether to hide run inputs. Can be a boolean or function to transform inputs.

hideOutputs

boolean | ((outputs: KVMap) => KVMap | Promise<KVMap>)

Whether to hide run outputs. Can be a boolean or function to transform outputs.

omitTracedRuntimeInfo

boolean

default:"false"

Whether to omit runtime information (SDK version, platform, etc.) from traced runs.

autoBatchTracing

boolean

default:"true"

Whether to automatically batch trace uploads.

batchSizeBytesLimit

number

Maximum size of a batch of runs in bytes.

batchSizeLimit

number

Maximum number of operations to batch in a single request.

maxIngestMemoryBytes

number

default:"1073741824"

Maximum total memory (in bytes) for both the AutoBatchQueue and batchIngestCaller queue. Defaults to 1GB.

blockOnRootRunFinalization

boolean

default:"false"

Whether to block on root run finalization. Set to true for synchronous tracing.

traceBatchConcurrency

number

default:"5"

Number of concurrent batch trace uploads.

manualFlushMode

boolean

default:"false"

Whether to require manual .flush() calls before sending traces. Useful for serverless environments.

tracingSamplingRate

number

Sampling rate for tracing (0.0 to 1.0). Samples at the trace level.

debug

boolean

default:"false"

Enable debug mode. If set, all sent HTTP requests will be logged.

disablePromptCache

boolean

default:"false"

Disable prompt caching for this client.

fetchOptions

RequestInit

Custom fetch options for HTTP requests.

Methods

createRun()

Create a new run (trace or span).

await client.createRun({
  name: "my-chain",
  run_type: "chain",
  inputs: { query: "Hello" },
  project_name: "my-project",
});

run

CreateRunParams

required

The run parameters

CreateRunParams properties

name

string

required

A human-readable name for the run.

inputs

KVMap

required

The inputs that were used to initiate the run.

run_type

string

required

The type of run (e.g., “llm”, “chain”, “tool”, “retriever”).

string

Unique identifier for the run. Auto-generated if not provided.

start_time

number | string

The epoch time at which the run started.

end_time

number | string

The epoch time at which the run ended.

outputs

KVMap

Outputs produced by the run.

error

string

Error message if the run failed.

project_name

string

The name of the project/session.

parent_run_id

string

ID of the parent run if this is a child run.

trace_id

string

Unique ID assigned to every run within this nested trace.

reference_example_id

string

ID of an example that might be related to this run.

updateRun()

Update an existing run.

await client.updateRun(runId, {
  outputs: { response: "Hello!" },
  end_time: Date.now(),
});

flush()

Flush current queued traces immediately.

await client.flush();

createProject()

Create a new project.

const project = await client.createProject({
  projectName: "my-project",
  description: "My LangSmith project",
});

params

CreateProjectParams

required

CreateProjectParams properties

projectName

string

required

The name of the project.

description

string | null

A description of the project.

metadata

Record<string, any> | null

Extra metadata for the project.

upsert

boolean

If true, update the project if it already exists.

referenceDatasetId

string | null

The reference dataset ID this project’s runs were generated on.

createDataset()

Create a new dataset.

const dataset = await client.createDataset("my-dataset", {
  description: "My evaluation dataset",
  dataType: "kv",
});

createExample()

Create an example in a dataset.

await client.createExample(
  { query: "What is LangSmith?" },
  { answer: "LangSmith is an observability platform" },
  {
    datasetName: "my-dataset",
    metadata: { source: "docs" },
  }
);

listRuns()

List runs from a project with filtering.

const runs = await client.listRuns({
  projectName: "my-project",
  limit: 10,
  filter: 'eq(run_type, "llm")',
});

params

ListRunsParams

ListRunsParams properties

projectId

string | string[]

The ID or IDs of the project(s) to filter by.

projectName

string | string[]

The name or names of the project(s) to filter by.

traceId

string

The ID of the trace to filter by.

isRoot

boolean

Whether to only include root runs.

runType

string

The run type to filter by (e.g., “llm”, “chain”).

error

boolean

Filter by error runs.

limit

number

The maximum number of runs to retrieve.

filter

string

Filter query string using LangSmith’s filter language. Supports comparators like eq, neq, gt, gte, lt, lte, has, and search.

startTime

Date

The start time to filter by.

createFeedback()

Create feedback for a run.

await client.createFeedback(runId, "quality", {
  score: 0.8,
  comment: "Good response",
});

getPrompt()

Retrieve a prompt from the LangSmith Hub.

const prompt = await client.getPrompt("my-prompt");
const promptAtCommit = await client.getPrompt("my-prompt:abc123");

Static methods

getDefaultClientConfig()

Get the default client configuration from environment variables.

const config = Client.getDefaultClientConfig();

apiUrl

string

API URL from LANGSMITH_ENDPOINT or default.

apiKey

string

API key from LANGSMITH_API_KEY.

hideInputs

boolean

Whether to hide inputs from LANGSMITH_HIDE_INPUTS.

hideOutputs

boolean

Whether to hide outputs from LANGSMITH_HIDE_OUTPUTS.

Example usage

import { Client } from "langsmith";

const client = new Client();

// Create a run
const runId = "550e8400-e29b-41d4-a716-446655440000";
await client.createRun({
  id: runId,
  name: "my-llm-call",
  run_type: "llm",
  inputs: { prompt: "Hello" },
  project_name: "my-project",
});

// Update the run with outputs
await client.updateRun(runId, {
  outputs: { response: "Hi there!" },
  end_time: Date.now(),
});

// Flush traces
await client.flush();

Tracing

Evaluation

Wrappers

Test Integrations

Utilities

Client

Constructor

Methods

createRun()

updateRun()

flush()

createProject()

createDataset()

createExample()

listRuns()

createFeedback()

getPrompt()

Static methods

getDefaultClientConfig()

Example usage

Build docs developers (and LLMs) love

Client

Tracing

Evaluation

Wrappers

Test Integrations

Utilities

​Constructor

​Methods

​createRun()

​updateRun()

​flush()

​createProject()

​createDataset()

​createExample()

​listRuns()

​createFeedback()

​getPrompt()

​Static methods

​getDefaultClientConfig()

​Example usage

Build docs developers (and LLMs) love

Constructor

Methods

createRun()

updateRun()

flush()

createProject()

createDataset()

createExample()

listRuns()

createFeedback()

getPrompt()

Static methods

getDefaultClientConfig()

Example usage