Class LangfuseClient

Main client for interacting with the Langfuse API.

The LangfuseClient provides access to all Langfuse functionality including:

Prompt management and retrieval
Dataset operations
Score creation and management
Media upload and handling
Direct API access for advanced use cases

Example

// Initialize with explicit credentials
const langfuse = new LangfuseClient({
  publicKey: "pk_...",
  secretKey: "sk_...",
  baseUrl: "https://cloud.langfuse.com"
});

// Or use environment variables
const langfuse = new LangfuseClient();

// Use the client
const prompt = await langfuse.prompt.get("my-prompt");
const compiledPrompt = prompt.compile({ variable: "value" });

Constructors

constructor

new LangfuseClient(params?: LangfuseClientParams): LangfuseClient
Creates a new LangfuseClient instance.
Parameters
- Optionalparams: LangfuseClientParams
  Configuration parameters. If not provided, will use environment variables.
Returns LangfuseClient
Throws
Will log warnings if required credentials are not provided
Example
```
// With explicit configuration
const client = new LangfuseClient({
  publicKey: "pk_...",
  secretKey: "sk_...",
  baseUrl: "https://your-instance.langfuse.com"
});

// Using environment variables
const client = new LangfuseClient();
```
- Defined in client/src/LangfuseClient.ts:197

Properties

api

api: LangfuseAPIClient

Direct access to the underlying Langfuse API client. Use this for advanced API operations not covered by the high-level managers.

createDataset

createDataset: (
request: CreateDatasetRequest,
requestOptions?: RequestOptions,
) => HttpResponsePromise<Dataset>

Type declaration

- (
  request: CreateDatasetRequest,
  requestOptions?: RequestOptions,
  ): HttpResponsePromise<Dataset>
- Create a dataset
  Parameters
  - request: CreateDatasetRequest
  - OptionalrequestOptions: RequestOptions
    Request-specific configuration.
  Returns HttpResponsePromise<Dataset>
  Throws
  LangfuseAPI.Error
  
  Throws
  LangfuseAPI.UnauthorizedError
  
  Throws
  LangfuseAPI.AccessDeniedError
  
  Throws
  LangfuseAPI.MethodNotAllowedError
  
  Throws
  LangfuseAPI.NotFoundError
  Example
```
await client.datasets.create({
        name: "name",
        description: undefined,
        metadata: undefined
    })
```

Deprecated

Use api.datasets.create instead

createDatasetItem

createDatasetItem: (
request: CreateDatasetItemRequest,
requestOptions?: RequestOptions,
) => HttpResponsePromise<DatasetItem>

Type declaration

- (
  request: CreateDatasetItemRequest,
  requestOptions?: RequestOptions,
  ): HttpResponsePromise<DatasetItem>
- Create a dataset item
  Parameters
  - request: CreateDatasetItemRequest
  - OptionalrequestOptions: RequestOptions
    Request-specific configuration.
  Returns HttpResponsePromise<DatasetItem>
  Throws
  LangfuseAPI.Error
  
  Throws
  LangfuseAPI.UnauthorizedError
  
  Throws
  LangfuseAPI.AccessDeniedError
  
  Throws
  LangfuseAPI.MethodNotAllowedError
  
  Throws
  LangfuseAPI.NotFoundError
  Example
```
await client.datasetItems.create({
        datasetName: "datasetName",
        input: undefined,
        expectedOutput: undefined,
        metadata: undefined,
        sourceTraceId: undefined,
        sourceObservationId: undefined,
        id: undefined,
        status: undefined
    })
```

Deprecated

Use api.datasetItems.create instead

createPrompt

createPrompt: {
    (body: CreateChatPromptBodyWithPlaceholders): Promise<ChatPromptClient>;
    (body: Omit<Text, "type"> & { type?: "text" }): Promise<TextPromptClient>;
    (body: Chat): Promise<ChatPromptClient>;
}

Type declaration

- (body: CreateChatPromptBodyWithPlaceholders): Promise<ChatPromptClient>
- Creates a new prompt in Langfuse.
  Parameters
  - body: CreateChatPromptBodyWithPlaceholders
    The prompt data to create (chat prompt)
  Returns Promise<ChatPromptClient>
  Promise that resolves to a ChatPromptClient
- (body: Omit<Text, "type"> & { type?: "text" }): Promise<TextPromptClient>
- Creates a new prompt in Langfuse.
  Parameters
  - body: Omit<Text, "type"> & { type?: "text" }
    The prompt data to create (text prompt)
  Returns Promise<TextPromptClient>
  Promise that resolves to a TextPromptClient
- (body: Chat): Promise<ChatPromptClient>
- Creates a new prompt in Langfuse.
  Parameters
  - body: Chat
    The prompt data to create (chat prompt)
  Returns Promise<ChatPromptClient>
  Promise that resolves to a ChatPromptClient

Deprecated

Use prompt.create instead

dataset

dataset: DatasetManager

Manager for dataset operations including retrieval and item linking.

fetchMedia

fetchMedia: (
mediaId: string,
requestOptions?: RequestOptions,
) => HttpResponsePromise<GetMediaResponse>

Type declaration

- (
  mediaId: string,
  requestOptions?: RequestOptions,
  ): HttpResponsePromise<GetMediaResponse>
- Get a media record
  Parameters
  - mediaId: string
    The unique langfuse identifier of a media record
  - OptionalrequestOptions: RequestOptions
    Request-specific configuration.
  Returns HttpResponsePromise<GetMediaResponse>
  Throws
  LangfuseAPI.Error
  
  Throws
  LangfuseAPI.UnauthorizedError
  
  Throws
  LangfuseAPI.AccessDeniedError
  
  Throws
  LangfuseAPI.MethodNotAllowedError
  
  Throws
  LangfuseAPI.NotFoundError
  Example
```
await client.media.get("mediaId")
```

Deprecated

Use api.media.get instead

fetchObservation

fetchObservation: (
observationId: string,
requestOptions?: RequestOptions,
) => HttpResponsePromise<ObservationsView>

Type declaration

- (
  observationId: string,
  requestOptions?: RequestOptions,
  ): HttpResponsePromise<ObservationsView>
- Get a observation
  Parameters
  - observationId: string
    The unique langfuse identifier of an observation, can be an event, span or generation
  - OptionalrequestOptions: RequestOptions
    Request-specific configuration.
  Returns HttpResponsePromise<ObservationsView>
  Throws
  LangfuseAPI.Error
  
  Throws
  LangfuseAPI.UnauthorizedError
  
  Throws
  LangfuseAPI.AccessDeniedError
  
  Throws
  LangfuseAPI.MethodNotAllowedError
  
  Throws
  LangfuseAPI.NotFoundError
  Example
```
await client.observations.get("observationId")
```

Deprecated

Use api.observations.get instead

fetchObservations

fetchObservations: (
request?: GetObservationsRequest,
requestOptions?: RequestOptions,
) => HttpResponsePromise<ObservationsViews>

Type declaration

- (
  request?: GetObservationsRequest,
  requestOptions?: RequestOptions,
  ): HttpResponsePromise<ObservationsViews>
- Get a list of observations
  Parameters
  - Optionalrequest: GetObservationsRequest
  - OptionalrequestOptions: RequestOptions
    Request-specific configuration.
  Returns HttpResponsePromise<ObservationsViews>
  Throws
  LangfuseAPI.Error
  
  Throws
  LangfuseAPI.UnauthorizedError
  
  Throws
  LangfuseAPI.AccessDeniedError
  
  Throws
  LangfuseAPI.MethodNotAllowedError
  
  Throws
  LangfuseAPI.NotFoundError
  Example
```
await client.observations.getMany()
```

Deprecated

Use api.observations.list instead

fetchSessions

fetchSessions: (
sessionId: string,
requestOptions?: RequestOptions,
) => HttpResponsePromise<SessionWithTraces>

Type declaration

- (
  sessionId: string,
  requestOptions?: RequestOptions,
  ): HttpResponsePromise<SessionWithTraces>
- Get a session. Please note that traces on this endpoint are not paginated, if you plan to fetch large sessions, consider GET /api/public/traces?sessionId=<sessionId>
  Parameters
  - sessionId: string
    The unique id of a session
  - OptionalrequestOptions: RequestOptions
    Request-specific configuration.
  Returns HttpResponsePromise<SessionWithTraces>
  Throws
  LangfuseAPI.Error
  
  Throws
  LangfuseAPI.UnauthorizedError
  
  Throws
  LangfuseAPI.AccessDeniedError
  
  Throws
  LangfuseAPI.MethodNotAllowedError
  
  Throws
  LangfuseAPI.NotFoundError
  Example
```
await client.sessions.get("sessionId")
```

Deprecated

Use api.sessions.get instead

fetchTrace

fetchTrace: (
traceId: string,
requestOptions?: RequestOptions,
) => HttpResponsePromise<TraceWithFullDetails>

Type declaration

- (
  traceId: string,
  requestOptions?: RequestOptions,
  ): HttpResponsePromise<TraceWithFullDetails>
- Get a specific trace
  Parameters
  - traceId: string
    The unique langfuse identifier of a trace
  - OptionalrequestOptions: RequestOptions
    Request-specific configuration.
  Returns HttpResponsePromise<TraceWithFullDetails>
  Throws
  LangfuseAPI.Error
  
  Throws
  LangfuseAPI.UnauthorizedError
  
  Throws
  LangfuseAPI.AccessDeniedError
  
  Throws
  LangfuseAPI.MethodNotAllowedError
  
  Throws
  LangfuseAPI.NotFoundError
  Example
```
await client.trace.get("traceId")
```

Deprecated

Use api.trace.get instead

fetchTraces

fetchTraces: (
request?: GetTracesRequest,
requestOptions?: RequestOptions,
) => HttpResponsePromise<Traces>

Type declaration

- (
  request?: GetTracesRequest,
  requestOptions?: RequestOptions,
  ): HttpResponsePromise<Traces>
- Get list of traces
  Parameters
  - Optionalrequest: GetTracesRequest
  - OptionalrequestOptions: RequestOptions
    Request-specific configuration.
  Returns HttpResponsePromise<Traces>
  Throws
  LangfuseAPI.Error
  
  Throws
  LangfuseAPI.UnauthorizedError
  
  Throws
  LangfuseAPI.AccessDeniedError
  
  Throws
  LangfuseAPI.MethodNotAllowedError
  
  Throws
  LangfuseAPI.NotFoundError
  Example
```
await client.trace.list()
```

Deprecated

Use api.trace.list instead

getDataset

getDataset: (
    name: string,
    options?: { fetchItemsPageSize: number },
) => Promise<
    Dataset & { items: (DatasetItem & { link: LinkDatasetItemFunction })[] },
>

Type declaration

- (
      name: string,
      options?: { fetchItemsPageSize: number },
  ): Promise<
      Dataset & { items: (DatasetItem & { link: LinkDatasetItemFunction })[] },
  >
- Retrieves a dataset by name along with all its items.
  
  This method automatically handles pagination to fetch all dataset items and enhances each item with a link function for easy experiment tracking.
  Parameters
  - name: string
    The name of the dataset to retrieve
  - Optionaloptions: { fetchItemsPageSize: number }
    Optional configuration for fetching
    - fetchItemsPageSize: number
      Number of items to fetch per page (default: 50)
  Returns Promise<
  Dataset & { items: (DatasetItem & { link: LinkDatasetItemFunction })[] },
  >
  Promise that resolves to the dataset with enhanced items
  Example
```
const dataset = await langfuse.dataset.get("my-dataset");

for (const item of dataset.items) {
  // Use the item data for your experiment
  const result = await processItem(item.input);

  // Link the result to the dataset item
  await item.link(
    { otelSpan: currentSpan },
    "experiment-run-1",
    { description: "Testing new model" }
  );
}
```

Deprecated

Use dataset.get instead

getDatasetItem

getDatasetItem: (
id: string,
requestOptions?: RequestOptions,
) => HttpResponsePromise<DatasetItem>

Type declaration

- (id: string, requestOptions?: RequestOptions): HttpResponsePromise<DatasetItem>
- Get a dataset item
  Parameters
  - id: string
  - OptionalrequestOptions: RequestOptions
    Request-specific configuration.
  Returns HttpResponsePromise<DatasetItem>
  Throws
  LangfuseAPI.Error
  
  Throws
  LangfuseAPI.UnauthorizedError
  
  Throws
  LangfuseAPI.AccessDeniedError
  
  Throws
  LangfuseAPI.MethodNotAllowedError
  
  Throws
  LangfuseAPI.NotFoundError
  Example
```
await client.datasetItems.get("id")
```

Deprecated

Use api.datasetItems.get instead

getDatasetRun

getDatasetRun: (
    datasetName: string,
    runName: string,
    requestOptions?: RequestOptions,
) => HttpResponsePromise<DatasetRunWithItems>

Type declaration

- (
      datasetName: string,
      runName: string,
      requestOptions?: RequestOptions,
  ): HttpResponsePromise<DatasetRunWithItems>
- Get a dataset run and its items
  Parameters
  - datasetName: string
  - runName: string
  - OptionalrequestOptions: RequestOptions
    Request-specific configuration.
  Returns HttpResponsePromise<DatasetRunWithItems>
  Throws
  LangfuseAPI.Error
  
  Throws
  LangfuseAPI.UnauthorizedError
  
  Throws
  LangfuseAPI.AccessDeniedError
  
  Throws
  LangfuseAPI.MethodNotAllowedError
  
  Throws
  LangfuseAPI.NotFoundError
  Example
```
await client.datasets.getRun("datasetName", "runName")
```

Deprecated

Use api.datasets.getRun instead

getDatasetRuns

getDatasetRuns: (
    datasetName: string,
    request?: GetDatasetRunsRequest,
    requestOptions?: RequestOptions,
) => HttpResponsePromise<PaginatedDatasetRuns>

Type declaration

- (
      datasetName: string,
      request?: GetDatasetRunsRequest,
      requestOptions?: RequestOptions,
  ): HttpResponsePromise<PaginatedDatasetRuns>
- Get dataset runs
  Parameters
  - datasetName: string
  - Optionalrequest: GetDatasetRunsRequest
  - OptionalrequestOptions: RequestOptions
    Request-specific configuration.
  Returns HttpResponsePromise<PaginatedDatasetRuns>
  Throws
  LangfuseAPI.Error
  
  Throws
  LangfuseAPI.UnauthorizedError
  
  Throws
  LangfuseAPI.AccessDeniedError
  
  Throws
  LangfuseAPI.MethodNotAllowedError
  
  Throws
  LangfuseAPI.NotFoundError
  Example
```
await client.datasets.getRuns("datasetName")
```

Deprecated

Use api.datasets.getRuns instead

getPrompt

getPrompt: {
    (
        name: string,
        options?: {
            cacheTtlSeconds?: number;
            fallback?: string;
            fetchTimeoutMs?: number;
            label?: string;
            maxRetries?: number;
            type?: "text";
            version?: number;
        },
    ): Promise<TextPromptClient>;
    (
        name: string,
        options?: {
            cacheTtlSeconds?: number;
            fallback?: ChatMessage[];
            fetchTimeoutMs?: number;
            label?: string;
            maxRetries?: number;
            type: "chat";
            version?: number;
        },
    ): Promise<ChatPromptClient>;
}

Type declaration

- (
      name: string,
      options?: {
          cacheTtlSeconds?: number;
          fallback?: string;
          fetchTimeoutMs?: number;
          label?: string;
          maxRetries?: number;
          type?: "text";
          version?: number;
      },
  ): Promise<TextPromptClient>
- Retrieves a text prompt by name.
  Parameters
  - name: string
    Name of the prompt to retrieve
  - Optionaloptions: {
        cacheTtlSeconds?: number;
        fallback?: string;
        fetchTimeoutMs?: number;
        label?: string;
        maxRetries?: number;
        type?: "text";
        version?: number;
    }
    Optional retrieval configuration
    - OptionalcacheTtlSeconds?: number
      Cache TTL in seconds (0 to disable caching)
    - Optionalfallback?: string
      Fallback text content if prompt fetch fails
    - OptionalfetchTimeoutMs?: number
      Request timeout in milliseconds
    - Optionallabel?: string
      Label to filter by
    - OptionalmaxRetries?: number
      Maximum retry attempts for failed requests
    - Optionaltype?: "text"
      Specify text prompt type
    - Optionalversion?: number
      Specific version to retrieve (defaults to latest)
  Returns Promise<TextPromptClient>
  Promise that resolves to a TextPromptClient
- (
      name: string,
      options?: {
          cacheTtlSeconds?: number;
          fallback?: ChatMessage[];
          fetchTimeoutMs?: number;
          label?: string;
          maxRetries?: number;
          type: "chat";
          version?: number;
      },
  ): Promise<ChatPromptClient>
- Retrieves a chat prompt by name.
  Parameters
  - name: string
    Name of the prompt to retrieve
  - Optionaloptions: {
        cacheTtlSeconds?: number;
        fallback?: ChatMessage[];
        fetchTimeoutMs?: number;
        label?: string;
        maxRetries?: number;
        type: "chat";
        version?: number;
    }
    Optional retrieval configuration
    - OptionalcacheTtlSeconds?: number
      Cache TTL in seconds (0 to disable caching)
    - Optionalfallback?: ChatMessage[]
      Fallback chat messages if prompt fetch fails
    - OptionalfetchTimeoutMs?: number
      Request timeout in milliseconds
    - Optionallabel?: string
      Label to filter by
    - OptionalmaxRetries?: number
      Maximum retry attempts for failed requests
    - type: "chat"
      Specify chat prompt type
    - Optionalversion?: number
      Specific version to retrieve (defaults to latest)
  Returns Promise<ChatPromptClient>
  Promise that resolves to a ChatPromptClient

Deprecated

Use prompt.get instead

media

media: MediaManager

Manager for media upload and reference resolution.

prompt

prompt: PromptManager

Manager for prompt operations including creation, retrieval, and caching.

resolveMediaReferences

resolveMediaReferences: <T>(
params: LangfuseMediaResolveMediaReferencesParams<T>,
) => Promise<T>

Type declaration

- <T>(params: LangfuseMediaResolveMediaReferencesParams<T>): Promise<T>
- Replaces media reference strings in an object with base64 data URIs.
  
  This method recursively traverses an object looking for media reference strings in the format "@@@langfuseMedia:...@@@". When found, it fetches the actual media content from Langfuse and replaces the reference string with a base64 data URI.
  
  If fetching media content fails for a reference string, a warning is logged and the reference string is left unchanged.
  Type Parameters
  - T
  Parameters
  - params: LangfuseMediaResolveMediaReferencesParams<T>
    Configuration object
  Returns Promise<T>
  A deep copy of the input object with media references resolved
  Example
```
const obj = {
  image: "@@@langfuseMedia:type=image/jpeg|id=123|source=bytes@@@",
  nested: {
    pdf: "@@@langfuseMedia:type=application/pdf|id=456|source=bytes@@@"
  }
};

const result = await langfuse.media.resolveReferences({
  obj,
  resolveWith: "base64DataUri"
});

// Result:
// {
//   image: "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
//   nested: {
//     pdf: "data:application/pdf;base64,JVBERi0xLjcK..."
//   }
// }
```

Deprecated

Use media.resolveReferences instead

score

score: ScoreManager

Manager for score creation and batch processing.

updatePrompt

updatePrompt: (
params: { name: string; newLabels: string[]; version: number },
) => Promise<Prompt>

Type declaration

- (
  params: { name: string; newLabels: string[]; version: number },
  ): Promise<Prompt>
- Updates the labels of an existing prompt version.
  Parameters
  - params: { name: string; newLabels: string[]; version: number }
    Update parameters
    - name: string
      Name of the prompt to update
    - newLabels: string[]
      New labels to apply to the prompt version
    - version: number
      Version number of the prompt to update
  Returns Promise<Prompt>
  Promise that resolves to the updated prompt
  Example
```
const updatedPrompt = await langfuse.prompt.update({
  name: "my-prompt",
  version: 1,
  newLabels: ["production", "v2"]
});
```

Deprecated

Use prompt.update instead

Methods

flush

flush(): Promise<void>
Flushes any pending score events to the Langfuse API.

This method ensures all queued scores are sent immediately rather than waiting for the automatic flush interval or batch size threshold.

Returns Promise<void>
Promise that resolves when all pending scores have been sent
Example
```
langfuse.score.create({ name: "quality", value: 0.8 });
await langfuse.flush(); // Ensures the score is sent immediately
```
- Defined in client/src/LangfuseClient.ts:276

getTraceUrl

getTraceUrl(traceId: string): Promise<string>
Generates a URL to view a specific trace in the Langfuse UI.
Parameters
- traceId: string
  The ID of the trace to generate a URL for
Returns Promise<string>
Promise that resolves to the trace URL
Example
```
const traceId = "trace-123";
const url = await langfuse.getTraceUrl(traceId);
console.log(`View trace at: ${url}`);
```
- Defined in client/src/LangfuseClient.ts:311

shutdown

shutdown(): Promise<void>
Gracefully shuts down the client by flushing all pending data.

This method should be called before your application exits to ensure all data is sent to Langfuse.

Returns Promise<void>
Promise that resolves when shutdown is complete
Example
```
// Before application exit
await langfuse.shutdown();
```
- Defined in client/src/LangfuseClient.ts:294

Class LangfuseClient

Example

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns LangfuseClient

Throws

Example

Properties

api

createDataset

Type declaration

Parameters

Returns HttpResponsePromise<Dataset>

Throws

Throws

Throws

Throws

Throws

Example

Deprecated

createDatasetItem

Type declaration

Parameters

Returns HttpResponsePromise<DatasetItem>

Throws

Throws

Throws

Throws

Throws

Example

Deprecated

createPrompt

Type declaration

Parameters

Returns Promise<ChatPromptClient>

Parameters

Returns Promise<TextPromptClient>

Parameters

Returns Promise<ChatPromptClient>

Deprecated

dataset

fetchMedia

Type declaration

Parameters

Returns HttpResponsePromise<GetMediaResponse>

Throws

Throws

Throws

Throws

Throws

Example

Deprecated

fetchObservation

Type declaration

Parameters

Returns HttpResponsePromise<ObservationsView>

Throws

Throws

Throws

Throws

Throws

Example

Deprecated

fetchObservations

Type declaration

Parameters

Returns HttpResponsePromise<ObservationsViews>

Throws

Throws

Throws

Throws

Throws

Example

Deprecated

fetchSessions

Returns Promise<
Dataset & { items: (DatasetItem & { link: LinkDatasetItemFunction })[] },
>