LangSmith Fetch (TypeScript)

TypeScript/Node.js port of langchain-ai/langsmith-fetch — a CLI tool for retrieving threads and traces from LangSmith projects. Designed for both human users and code agents conducting testing and debugging work.

Installation

# Run directly with npx (no install needed)
npx langsmith-fetch --help

# Or install globally
npm install -g langsmith-fetch

Requires Node.js >= 18.

Setup

Set your LangSmith API key as an environment variable:

export LANGSMITH_API_KEY=lsv2_pt_...

Optional environment variables:

• LANGSMITH_PROJECT — Project name (auto-discovers the UUID)
• LANGSMITH_PROJECT_UUID — Project UUID (skips lookup)
• LANGSMITH_ENDPOINT — Only needed for self-hosted LangSmith instances

Alternatively, store configuration in ~/.langsmith-cli/config.yaml:

api-key: lsv2_pt_...
project-uuid: 867da8a9-4f31-4ef1-8333-03117ea98f32
default-format: pretty

Commands

LangSmith organizes data into three levels: Runs (individual LLM calls), Traces (collections of runs), and Threads (collections of traces representing conversations).

Fetch a single trace

langsmith-fetch trace <trace-id>
langsmith-fetch trace <trace-id> --format json
langsmith-fetch trace <trace-id> --include-metadata
langsmith-fetch trace <trace-id> --include-metadata --include-feedback
langsmith-fetch trace <trace-id> --file output.json

Fetch a single thread

langsmith-fetch thread <thread-id> --project-uuid <uuid>
langsmith-fetch thread <thread-id> --format json

Bulk fetch traces

# Save to directory (recommended)
langsmith-fetch traces ./my-traces --project-uuid <uuid> --limit 10

# Print to stdout
langsmith-fetch traces --project-uuid <uuid> --limit 5 --format json

# With time filtering
langsmith-fetch traces ./dir --project-uuid <uuid> --last-n-minutes 60
langsmith-fetch traces ./dir --project-uuid <uuid> --since 2025-12-09T10:00:00Z

# With metadata and custom filenames
langsmith-fetch traces ./dir --project-uuid <uuid> --limit 10 --include-metadata --filename-pattern "trace_{index}.json"

Bulk fetch threads

# Save to directory (recommended)
langsmith-fetch threads ./my-threads --project-uuid <uuid> --limit 10

# Print to stdout
langsmith-fetch threads --project-uuid <uuid> --limit 5 --format json

# With time filtering
langsmith-fetch threads ./dir --project-uuid <uuid> --last-n-minutes 30

View configuration

langsmith-fetch config show

Output Formats

| Format | Flag | Description | |--------|------|-------------| | Pretty | --format pretty | Human-readable with section headers (default) | | JSON | --format json | Pretty-printed JSON | | Raw | --format raw | Compact single-line JSON for piping |

Common Options

| Option | Description | |--------|-------------| | --format <format> | Output format: pretty, json, raw | | --file <path> | Save output to file instead of stdout | | -n, --limit <n> | Maximum number of items to fetch | | --last-n-minutes <n> | Only fetch items from the last N minutes | | --since <timestamp> | Only fetch items since ISO timestamp | | --project-uuid <uuid> | LangSmith project UUID | | --include-metadata | Include run metadata (status, timing, tokens, costs) | | --include-feedback | Include feedback data | | --no-progress | Disable progress bar | | --max-concurrent <n> | Maximum concurrent fetches (default: 5) | | --filename-pattern <p> | Custom filename pattern for directory mode |

Development

pnpm install          # install dependencies
pnpm build            # compile TypeScript
pnpm test             # run tests (vitest)
pnpm lint             # lint with eslint
pnpm format           # format with prettier

License

MIT