Langfuse.Client (Langfuse v0.1.0)
View SourceDirect access to the Langfuse REST API.
This module provides functions for interacting with Langfuse management APIs that are not covered by the tracing SDK. Use this for datasets, score configurations, listing traces/sessions, and other administrative operations.
Datasets
Create and manage evaluation datasets:
{:ok, dataset} = Langfuse.Client.create_dataset(name: "qa-eval")
{:ok, item} = Langfuse.Client.create_dataset_item(
dataset_name: "qa-eval",
input: %{question: "What is Elixir?"},
expected_output: %{answer: "A functional programming language"}
)Dataset Runs
Track evaluation runs against datasets:
{:ok, run} = Langfuse.Client.create_dataset_run(
name: "eval-2025-01",
dataset_name: "qa-eval"
)
{:ok, _} = Langfuse.Client.create_dataset_run_item(
run_name: "eval-2025-01",
dataset_item_id: item["id"],
trace_id: trace.id
)Querying Data
List and retrieve traces, sessions, and scores:
{:ok, traces} = Langfuse.Client.list_traces(limit: 10, user_id: "user-123")
{:ok, trace} = Langfuse.Client.get_trace("trace-id")
{:ok, sessions} = Langfuse.Client.list_sessions(limit: 50)Score Configurations
Manage score configurations:
{:ok, config} = Langfuse.Client.create_score_config(
name: "accuracy",
data_type: "NUMERIC",
min_value: 0,
max_value: 1
)Summary
Types
API response result.
Functions
Creates a new dataset.
Creates a dataset item.
Creates a dataset run.
Creates a dataset run item linking a trace to a dataset item.
Creates a custom model definition.
Creates a new prompt version.
Creates a score configuration.
Makes a raw DELETE request to the Langfuse API.
Deletes a dataset by name.
Deletes a dataset item by ID.
Deletes a dataset run.
Deletes a custom model definition.
Deletes a score by ID.
Makes a raw GET request to the Langfuse API.
Gets a dataset by name.
Gets a dataset item by ID.
Gets a dataset run by name.
Gets a model by ID.
Gets an observation by ID.
Gets a prompt by name.
Gets a score by ID.
Gets a score configuration by ID.
Gets a session by ID.
Gets a trace by ID.
Lists dataset items.
Lists dataset run items.
Lists runs for a dataset.
Lists datasets.
Lists available models with pricing information.
Lists observations.
Lists prompts with pagination and filtering.
Lists score configurations.
Lists scores.
Lists sessions.
Lists traces.
Makes a raw PATCH request to the Langfuse API.
Makes a raw POST request to the Langfuse API.
Updates a dataset item.
Updates labels for a specific prompt version.
Types
Functions
Creates a new dataset.
Options
:name- Dataset name (required):description- Dataset description:metadata- Additional metadata
Examples
Langfuse.Client.create_dataset(name: "qa-evaluation")
#=> {:ok, %{"id" => "...", "name" => "qa-evaluation"}}
Langfuse.Client.create_dataset(
name: "rag-benchmark",
description: "Evaluation dataset for RAG pipeline",
metadata: %{version: "1.0"}
)Creates a dataset item.
Options
:dataset_name- Dataset name (required):input- Input data (required):expected_output- Expected output data:metadata- Additional metadata:source_trace_id- Source trace ID:source_observation_id- Source observation ID:status- Item status ("ACTIVE" or "ARCHIVED")
Examples
Langfuse.Client.create_dataset_item(
dataset_name: "qa-evaluation",
input: %{question: "What is Elixir?"},
expected_output: %{answer: "A functional programming language"}
)
#=> {:ok, %{"id" => "...", "input" => %{...}}}Creates a dataset run.
A dataset run represents a single evaluation pass over a dataset, linking trace executions to dataset items for comparison.
Options
:name- Run name (required):dataset_name- Dataset name (required):description- Run description:metadata- Additional metadata
Examples
Langfuse.Client.create_dataset_run(
name: "eval-2025-01-15",
dataset_name: "qa-evaluation"
)
#=> {:ok, %{"name" => "eval-2025-01-15", ...}}
Langfuse.Client.create_dataset_run(
name: "gpt4-vs-claude",
dataset_name: "qa-evaluation",
description: "Comparing GPT-4 and Claude responses",
metadata: %{model: "gpt-4"}
)Creates a dataset run item linking a trace to a dataset item.
This connects an execution trace to a specific dataset item, enabling comparison between the actual output and expected output.
Options
:run_name- Run name (required):run_description- Run description:dataset_item_id- Dataset item ID (required):trace_id- Trace ID (required):observation_id- Observation ID (to link specific span/generation):metadata- Additional metadata
Examples
Langfuse.Client.create_dataset_run_item(
run_name: "eval-2025-01-15",
dataset_item_id: "item-abc-123",
trace_id: "trace-xyz-789"
)
#=> {:ok, %{"id" => "...", "runName" => "eval-2025-01-15", ...}}Creates a custom model definition.
Custom models allow you to define pricing for models not in Langfuse's default model list, enabling accurate cost tracking.
Options
:model_name- Model identifier (required). Must match what's sent in generations.:match_pattern- Regex pattern for matching model names (required).:input_price- Price per input token in USD (required).:output_price- Price per output token in USD (required).:total_price- Fixed price per request (optional, alternative to token pricing).:unit- Pricing unit: "TOKENS", "CHARACTERS", "IMAGES", etc. (default: "TOKENS"):tokenizer_id- Tokenizer to use for token counting.:tokenizer_config- Tokenizer configuration map.
Examples
Langfuse.Client.create_model(
model_name: "my-custom-model",
match_pattern: "my-custom-.*",
input_price: 0.0001,
output_price: 0.0002,
unit: "TOKENS"
)Creates a new prompt version.
Options
:name- Prompt name (required):prompt- Prompt content (required). String for text, list of messages for chat.:type- Prompt type: "text" or "chat" (default: "text"):labels- List of labels (e.g., ["production", "latest"]):tags- List of tags:config- Configuration map (model parameters, etc.)
Examples
Langfuse.Client.create_prompt(
name: "greeting",
prompt: "Hello {{name}}!",
labels: ["production"]
)
Langfuse.Client.create_prompt(
name: "chat-assistant",
type: "chat",
prompt: [
%{"role" => "system", "content" => "You are helpful."},
%{"role" => "user", "content" => "{{question}}"}
]
)Creates a score configuration.
Score configurations define the schema for scores, including allowed values, ranges, and categories.
Options
:name- Config name (required):data_type- One of "NUMERIC", "CATEGORICAL", "BOOLEAN" (required):min_value- Minimum value (for numeric):max_value- Maximum value (for numeric):categories- List of category maps (for categorical):description- Config description
Examples
Langfuse.Client.create_score_config(
name: "accuracy",
data_type: "NUMERIC",
min_value: 0,
max_value: 1
)
#=> {:ok, %{"id" => "...", "name" => "accuracy", ...}}
Langfuse.Client.create_score_config(
name: "sentiment",
data_type: "CATEGORICAL",
categories: [
%{label: "positive", value: 1},
%{label: "neutral", value: 0},
%{label: "negative", value: -1}
]
)Makes a raw DELETE request to the Langfuse API.
Examples
Langfuse.Client.delete("/api/public/scores/score-abc-123")
#=> :okDeletes a dataset by name.
This operation is irreversible. All items and runs in the dataset will also be deleted.
Examples
Langfuse.Client.delete_dataset("qa-evaluation")
#=> :okDeletes a dataset item by ID.
Examples
Langfuse.Client.delete_dataset_item("item-abc-123")
#=> :okDeletes a dataset run.
This operation is irreversible. All run items will also be deleted.
Examples
Langfuse.Client.delete_dataset_run("qa-evaluation", "eval-2025-01-15")
#=> :okDeletes a custom model definition.
Only custom models created via the API can be deleted. Built-in models cannot be deleted.
Examples
Langfuse.Client.delete_model("model-abc-123")
#=> :okDeletes a score by ID.
Examples
Langfuse.Client.delete_score("score-abc-123")
#=> :okMakes a raw GET request to the Langfuse API.
Use this for API endpoints not covered by the higher-level functions.
Examples
Langfuse.Client.get("/api/public/health")
#=> {:ok, %{"status" => "OK"}}
Langfuse.Client.get("/api/public/traces", limit: 5)Gets a dataset by name.
Examples
Langfuse.Client.get_dataset("qa-evaluation")
#=> {:ok, %{"id" => "...", "name" => "qa-evaluation", "items" => [...]}}Gets a dataset item by ID.
Examples
Langfuse.Client.get_dataset_item("item-abc-123")
#=> {:ok, %{"id" => "item-abc-123", "input" => %{...}, "expectedOutput" => %{...}}}Gets a dataset run by name.
Examples
Langfuse.Client.get_dataset_run("qa-evaluation", "eval-2025-01-15")
#=> {:ok, %{"name" => "eval-2025-01-15", "datasetName" => "qa-evaluation", ...}}Gets a model by ID.
Examples
Langfuse.Client.get_model("model-abc-123")
#=> {:ok, %{"id" => "model-abc-123", "modelName" => "gpt-4", ...}}Gets an observation by ID.
Observations include spans, generations, and events within a trace.
Examples
Langfuse.Client.get_observation("obs-abc-123")
#=> {:ok, %{"id" => "obs-abc-123", "type" => "GENERATION", "name" => "llm-call", ...}}Gets a prompt by name.
Returns the prompt with optional version or label filtering. If neither version nor label is specified, returns the latest production version.
For cached prompt fetching with variable compilation, use Langfuse.Prompt.get/2.
Options
:version- Specific version number to fetch:label- Label to fetch (e.g., "production", "latest")
Examples
Langfuse.Client.get_prompt("my-prompt")
#=> {:ok, %{"name" => "my-prompt", "version" => 1, "prompt" => "...", ...}}
Langfuse.Client.get_prompt("my-prompt", version: 2)
Langfuse.Client.get_prompt("my-prompt", label: "production")Gets a score by ID.
Examples
Langfuse.Client.get_score("score-abc-123")
#=> {:ok, %{"id" => "score-abc-123", "name" => "accuracy", "value" => 0.95}}Gets a score configuration by ID.
Examples
Langfuse.Client.get_score_config("config-abc-123")
#=> {:ok, %{"id" => "config-abc-123", "name" => "accuracy", "dataType" => "NUMERIC"}}Gets a session by ID.
Examples
Langfuse.Client.get_session("session-abc-123")
#=> {:ok, %{"id" => "session-abc-123", "traces" => [...]}}Gets a trace by ID.
Examples
Langfuse.Client.get_trace("trace-abc-123")
#=> {:ok, %{"id" => "trace-abc-123", "name" => "chat-request", "observations" => [...]}}Lists dataset items.
Options
:limit- Maximum number of results (default: 50):page- Page number for pagination (1-indexed):dataset_name- Filter by dataset name
Examples
Langfuse.Client.list_dataset_items()
#=> {:ok, %{"data" => [...], "meta" => %{...}}}
Langfuse.Client.list_dataset_items(dataset_name: "qa-evaluation", limit: 10)Lists dataset run items.
Options
:limit- Maximum number of results (default: 50):page- Page number for pagination (1-indexed):run_name- Filter by run name:dataset_item_id- Filter by dataset item ID
Examples
Langfuse.Client.list_dataset_run_items()
#=> {:ok, %{"data" => [...], "meta" => %{...}}}
Langfuse.Client.list_dataset_run_items(run_name: "eval-2025-01-15")Lists runs for a dataset.
Options
:limit- Maximum number of results (default: 50):page- Page number for pagination (1-indexed)
Examples
Langfuse.Client.list_dataset_runs("qa-evaluation")
#=> {:ok, %{"data" => [...], "meta" => %{...}}}
Langfuse.Client.list_dataset_runs("qa-evaluation", limit: 5)Lists datasets.
Options
:limit- Maximum number of results (default: 50):page- Page number for pagination (1-indexed)
Examples
Langfuse.Client.list_datasets()
#=> {:ok, %{"data" => [...], "meta" => %{"page" => 1, "totalPages" => 1}}}
Langfuse.Client.list_datasets(limit: 10, page: 2)Lists available models with pricing information.
Returns both built-in models and custom models you've created.
Options
:limit- Maximum number of results (default: 50):page- Page number for pagination (1-indexed)
Examples
Langfuse.Client.list_models()
#=> {:ok, %{"data" => [...], "meta" => %{...}}}Lists observations.
Options
:limit- Maximum number of results (default: 50):page- Page number for pagination (1-indexed):trace_id- Filter by trace ID:name- Filter by observation name:type- Filter by type ("SPAN", "GENERATION", "EVENT"):user_id- Filter by user ID:parent_observation_id- Filter by parent observation
Examples
Langfuse.Client.list_observations(trace_id: "trace-abc-123")
#=> {:ok, %{"data" => [...], "meta" => %{...}}}
Langfuse.Client.list_observations(type: "GENERATION", limit: 10)Lists prompts with pagination and filtering.
Options
:limit- Maximum number of results (default: 50):page- Page number for pagination (1-indexed):name- Filter by prompt name:label- Filter by label:tag- Filter by tag
Examples
Langfuse.Client.list_prompts()
#=> {:ok, %{"data" => [...], "meta" => %{"page" => 1, "totalPages" => 5}}}
Langfuse.Client.list_prompts(limit: 10, name: "chat-template")
Langfuse.Client.list_prompts(label: "production")Lists score configurations.
Options
:limit- Maximum number of results (default: 50):page- Page number for pagination (1-indexed)
Examples
Langfuse.Client.list_score_configs()
#=> {:ok, %{"data" => [...], "meta" => %{...}}}Lists scores.
Options
:limit- Maximum number of results (default: 50):page- Page number for pagination (1-indexed):trace_id- Filter by trace ID:user_id- Filter by user ID:name- Filter by score name:data_type- Filter by data type ("NUMERIC", "CATEGORICAL", "BOOLEAN")
Examples
Langfuse.Client.list_scores()
#=> {:ok, %{"data" => [...], "meta" => %{...}}}
Langfuse.Client.list_scores(trace_id: "trace-abc-123")
Langfuse.Client.list_scores(name: "accuracy", data_type: "NUMERIC")Lists sessions.
Options
:limit- Maximum number of results (default: 50):page- Page number for pagination (1-indexed):from_timestamp- Filter from timestamp (ISO 8601):to_timestamp- Filter to timestamp (ISO 8601)
Examples
Langfuse.Client.list_sessions()
#=> {:ok, %{"data" => [...], "meta" => %{...}}}
Langfuse.Client.list_sessions(limit: 20)Lists traces.
Options
:limit- Maximum number of results (default: 50):page- Page number for pagination (1-indexed):user_id- Filter by user ID:session_id- Filter by session ID:name- Filter by name:tags- Filter by tags (list of strings):from_timestamp- Filter from timestamp (ISO 8601):to_timestamp- Filter to timestamp (ISO 8601)
Examples
Langfuse.Client.list_traces()
#=> {:ok, %{"data" => [...], "meta" => %{...}}}
Langfuse.Client.list_traces(user_id: "user-123", limit: 10)
Langfuse.Client.list_traces(
session_id: "session-456",
from_timestamp: "2025-01-01T00:00:00Z"
)Makes a raw PATCH request to the Langfuse API.
Examples
Langfuse.Client.patch("/api/public/v2/dataset-items/item-123", %{status: "ARCHIVED"})
#=> {:ok, %{"id" => "item-123", "status" => "ARCHIVED"}}Makes a raw POST request to the Langfuse API.
Use this for API endpoints not covered by the higher-level functions.
Examples
Langfuse.Client.post("/api/public/v2/datasets", %{name: "my-dataset"})
#=> {:ok, %{"id" => "...", "name" => "my-dataset"}}Updates a dataset item.
Options
:input- Updated input data:expected_output- Updated expected output:metadata- Updated metadata:status- Updated status ("ACTIVE" or "ARCHIVED")
Examples
Langfuse.Client.update_dataset_item("item-abc-123",
expected_output: %{answer: "Updated answer"},
status: "ARCHIVED"
)
#=> {:ok, %{"id" => "item-abc-123", ...}}@spec update_prompt_labels(String.t(), pos_integer(), keyword()) :: response()
Updates labels for a specific prompt version.
Options
:labels- New list of labels for this version
Examples
Langfuse.Client.update_prompt_labels("my-prompt", 3, labels: ["production", "v3"])