Langfuse
App · 24 actions
Automate around your LLM app in Langfuse: list and read traces with their cost, log traces and generations, score them, get prompts with their variables filled in, save and promote prompt versions, keep test datasets and read daily cost and tokens. Start a workflow on a new trace, a low score or negative feedback, a new prompt version or a label moved.
Actions
| Action | What it does |
|---|---|
| Add comment | Add a comment to a trace, observation, session or prompt, such as what a reviewer found or what was done about it. |
| Add dataset item | Add a test case to a dataset: an input with the expected output, such as a question a user asked and the answer it should have got, optionally from a trace. |
| Add observation to trace | Add a step to a trace logged earlier: a span, a generation (with model, tokens and cost), an event or a tool call, inside the trace or one of its observations. |
| Add score | Score a trace, an observation in it, or a session: a number, true or false, a category or text, such as a user's thumbs down or a reviewer's rating. |
| Create dataset | Create a dataset to collect test cases in, such as questions with their right answers. |
| Create prompt version | Save a new version of a prompt, or a new prompt: text, or chat messages, with labels such as staging, tags and a config. |
| Delete dataset item | Delete an item from its dataset, with its results in past runs. |
| Delete prompt | Delete one version of a prompt, or the whole prompt with every version. |
| Delete score | Delete a score, such as one given by mistake. |
| Delete trace | Delete a trace with its observations and scores, such as when a user asks for their data to be removed. |
| Get daily usage | Get cost, tokens, traces and observations per day, for the whole project or one trace name, user, tag or environment, optionally split by model: for a daily cost report or a budget alert. |
| Get prompt | Get a prompt by label (production unless you pick another) or version, with its variables filled in, ready to send to a model, as text or chat messages, and its config. |
| Get session | Get a session (a conversation) with its traces in order, their inputs and outputs, and what it cost. |
| Get trace | Get a trace with every observation in it (each step, model call, tokens and cost) and its scores. |
| Label prompt version | Move labels such as production to a version of a prompt; they leave the version that had them. |
| List comments | List comments, the newest first, on one trace, observation, session or prompt, or on every one of a kind. |
| List dataset items | List a dataset's active items, the newest first, with their inputs and expected outputs. |
| List dataset runs | List a dataset's runs (experiments), the latest first, with how many items each ran and their scores. |
| List observations | List recent observations, the latest first: generations of a model, the steps of one trace, or the ones that went wrong, with their tokens and cost. |
| List prompts | List prompts with their versions, labels and tags. |
| List score configs | List the project's score configs: each score's name, type, allowed range or categories. |
| List scores | List recent scores, the latest first, by name, trace, session, source and value range, such as every low helpfulness score this week, with their average. |
| List traces | List recent traces, the latest first, by name, user, session, tags and environment, with each one's input, output, time taken, cost and tokens. |
| Log trace | Log a trace to Langfuse, such as a model call a workflow made: one span or generation with its input, output, user, session, tags and, for a generation, model, tokens and cost. |
Add comment
Add a comment to a trace, observation, session or prompt, such as what a reviewer found or what was done about it.
Inputs
- On
object_typetext - What to comment on. Defaults to Trace.One of:
TRACE,OBSERVATION,SESSION,PROMPT. Default:TRACE. - ID
object_idtextRequired - The ID of the trace, observation or session (or the prompt's ID).
- Comment
contenttextRequired - What it says, up to 5,000 characters. Markdown works.
Outputs
contenttext- What it says
idtext- The comment's ID
object_idtext- The ID of what it is on
object_typetext- What it is on: TRACE, OBSERVATION, SESSION or PROMPT
Example output
{
"content": "Escalated to billing: refund issued.",
"id": "cm8z3comm0001",
"object_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"object_type": "TRACE"
}Add dataset item
Add a test case to a dataset: an input with the expected output, such as a question a user asked and the answer it should have got, optionally from a trace.
Inputs
- Dataset
datasettextRequired - The dataset: pick one, or type its name.
- Input
inputtextRequired - What the test gives your app, such as {"question": "Why was I charged twice?"}.
- Expected output
expected_outputtext - The right answer.
- Metadata
metadataobject - More about it, such as {"topic": "billing"}.
- From trace
source_trace_idtext - The trace it was taken from, to link the two.
- From observation
source_observation_idtext - The observation in that trace it was taken from.
- Item ID
item_idtext - An ID for it, so adding it again changes it rather than adding another. Leave blank for a new one.
- Status
statustext - Active items are used in runs; archived ones aren't. Defaults to Active.One of:
ACTIVE,ARCHIVED. Default:ACTIVE.
Outputs
createdtext- When it was added (ISO 8601)
dataset_nametext- The dataset it is in
expected_outputtext- What the right answer is, as text
idtext- The item's ID
inputtext- Its input, as text (often JSON)
metadataobject- Its metadata
source_observation_idtext- The observation it was made from
source_trace_idtext- The trace it was made from; empty if none
statustext- ACTIVE or ARCHIVED
updatedtext- When it was last changed (ISO 8601)
Example output
{
"created": "2026-11-12T09:40:00.000Z",
"dataset_name": "billing-questions",
"expected_output": "A hold that drops off in 3 days",
"id": "a1d0c6e8-3b2f-4e5a-9c7d-1f2e3d4c5b6a",
"input": "{\"question\": \"Why was I charged twice?\"}",
"metadata": {
"topic": "billing"
},
"source_observation_id": "",
"source_trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"status": "ACTIVE",
"updated": "2026-11-12T09:40:00.000Z"
}Add observation to trace
Add a step to a trace logged earlier: a span, a generation (with model, tokens and cost), an event or a tool call, inside the trace or one of its observations.
Inputs
- Trace ID
trace_idtextRequired - The trace to add to: the trace_id of Log trace.
- Name
nametextRequired - What this step was, such as retrieve-docs or call-model.
- Type
observation_typetext - What it records. Defaults to Generation when a model is given, otherwise Span.One of:
span,generation,event,agent,tool,retriever. - Inside observation
parent_observation_idtext - The observation to put it inside, such as the observation_id of Log trace. Defaults to the trace's first.
- Input
inputtext - What went in, such as the user's question or {"messages": [...]}. JSON is kept as JSON.
- Output
outputtext - What came out, such as the model's answer. JSON is kept as JSON.
- Model
modeltext - For a generation: the model called, such as gpt-4o-mini. Langfuse works out the cost from it and the tokens when it knows the model.
- Input tokens
input_tokensnumber - For a generation: tokens sent to the model.At least 0.
- Output tokens
output_tokensnumber - For a generation: tokens the model wrote.At least 0.
- Cost (USD)
costnumber - For a generation: what it cost in US dollars, such as 0.0021. Leave blank to let Langfuse work it out.At least 0.
- Prompt
prompt_nametext - The Langfuse prompt it used, to link the two.
- Prompt version
prompt_versionnumber - That prompt's version, such as the version of Get prompt.At least 1.
- Level
leveltext - How it went: Error or Warning marks it in Langfuse. Defaults to Default.One of:
DEBUG,DEFAULT,WARNING,ERROR. Default:DEFAULT. - Status message
status_messagetext - What to say about how it went, such as the error.
- Metadata
metadataobject - More about it, such as {"source": "faq"}.
- Start time
start_timedate and time - When it started. Defaults to now.
- End time
end_timedate and time - When it ended. Defaults to the start time.
Outputs
linktext- A link to the trace in Langfuse
nametext- Its name
observation_idtext- The new observation's ID
observation_typetext- What it is: SPAN, GENERATION, EVENT and so on
parent_observation_idtext- The observation it was put inside
trace_idtext- The trace it was added to
Example output
{
"link": "https://cloud.langfuse.com/project/cm8x2k1lq0001/traces/4bf92f3577b34da6a3ce929d0e0e4736",
"name": "retrieve-docs",
"observation_id": "b7ad6b7169203331",
"observation_type": "RETRIEVER",
"parent_observation_id": "00f067aa0ba902b7",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}Add score
Score a trace, an observation in it, or a session: a number, true or false, a category or text, such as a user's thumbs down or a reviewer's rating.
Inputs
- Score name
nametextRequired - What it measures, such as helpfulness or user-feedback.
- Value
valuetextRequired - The score: a number such as 0.8, true or false, or a category such as good.
- Trace ID
trace_idtext - The trace to score.
- Observation ID
observation_idtext - An observation in that trace to score instead of the whole trace.
- Session ID
session_idtext - A session to score, instead of a trace.
- Type
data_typetext - What kind of value it is. Defaults to reading it from the value: a number, true or false, or else a category.One of:
AUTO(From the value),NUMERIC(Number),BOOLEAN(True or false),CATEGORICAL(Category),TEXT. Default:AUTO. - Score config
config_idtext - A score config it follows, which sets its name's type and allowed values.
- Comment
commenttext - Why it got this score.
- Metadata
metadataobject - More about it, such as {"reviewer": "ana"}.
- Environment
environmenttext - Its environment, such as production.
- Score ID
score_idtext - An ID for it, so sending it again changes it rather than adding another. Leave blank for a new one.
Outputs
acceptedtrue/false- Whether Langfuse accepted it
data_typetext- NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or FROM_CONFIG
idtext- The score's ID, for Delete score
nametext- What it measures
observation_idtext- The observation it scores
session_idtext- The session it scores
trace_idtext- The trace it scores
valuetext- The value sent
Example output
{
"accepted": true,
"data_type": "NUMERIC",
"id": "7f4e9a2c-0b1d-4c3e-9f8a-6b5d4c3e2f1a",
"name": "helpfulness",
"observation_id": "",
"session_id": "",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"value": "0.8"
}Create dataset
Create a dataset to collect test cases in, such as questions with their right answers. One with that name already is updated.
Inputs
- Name
nametextRequired - The dataset's name, such as billing-questions.
- Description
descriptiontext - What it holds.
- Metadata
metadataobject - More about it, such as {"owner": "ml-team"}.
Outputs
createdtext- When it was made (ISO 8601)
descriptiontext- Its description
idtext- The dataset's ID
linktext- A link to the dataset in Langfuse
metadataobject- Its metadata
nametext- Its name
updatedtext- When it was last changed (ISO 8601)
Example output
{
"created": "2026-11-01T10:00:00.000Z",
"description": "Billing questions with the right answers",
"id": "cm8z2data0001",
"link": "https://cloud.langfuse.com/project/cm8x2k1lq0001/datasets/cm8z2data0001",
"metadata": {
"owner": "ml-team"
},
"name": "billing-questions",
"updated": "2026-11-12T09:00:00.000Z"
}Create prompt version
Save a new version of a prompt, or a new prompt: text, or chat messages, with labels such as staging, tags and a config.
Inputs
- Prompt
nametextRequired - The prompt's name: pick one for a new version, or type a new name.
- Prompt
prompttextRequired - The prompt's text, with {{variables}} to fill in. For a chat prompt, its messages as JSON, such as [{"role": "system", "content": "You help with {{topic}}."}].
- Type
prompt_typetext - Text, or chat messages. Defaults to chat when the prompt is a JSON list of messages, otherwise text; a new version must keep the prompt's type.One of:
auto(From the prompt),text,chat. Default:auto. - Labels
labelslist - Labels for this version, such as staging or production. A label moves here from the version that had it.
- Tags
tagslist - Tags for the prompt.
- Config
configobject - Settings for it, such as {"model": "gpt-4o-mini", "temperature": 0}.
- Change note
commit_messagetext - What changed in this version.
Outputs
commit_messagetext- The note saved with this version
compiledtext- The prompt with the variables you gave filled in, ready to send to a model (a chat prompt as role: content lines)
compiled_messageslist- A chat prompt's messages with the variables filled in
configobject- Its config, such as the model and temperature
idtext- The prompt version's ID, for Add comment
labelslist- This version's labels, such as production and latest
linktext- A link to the prompt version in Langfuse
messageslist- A chat prompt's messages as written; empty for a text prompt
missing_variableslist- The variables it has that you didn't give
nametext- The prompt's name
prompttext- The prompt as written, with its {{variables}}; a chat prompt as role: content lines
tagslist- The prompt's tags
typetext- text or chat
variableslist- The {{variables}} the prompt has
versionnumber- The version's number
Example output
{
"commit_message": "Shorter answers",
"compiled": "system: You answer billing questions for Acme.\n\nuser: Why was I charged twice?",
"compiled_messages": [
{
"content": "You answer billing questions for Acme.",
"role": "system"
},
{
"content": "Why was I charged twice?",
"role": "user"
}
],
"config": {
"model": "gpt-4o-mini",
"temperature": 0.2
},
"id": "c01951f3-b3a4-4e3d-a748-29829e736e92",
"labels": [
"production",
"latest"
],
"link": "https://cloud.langfuse.com/project/cm8x2k1lq0001/prompts/support-answer?version=4",
"messages": [
{
"content": "You answer billing questions for {{company}}.",
"role": "system"
},
{
"content": "{{question}}",
"role": "user"
}
],
"missing_variables": [],
"name": "support-answer",
"prompt": "system: You answer billing questions for {{company}}.\n\nuser: {{question}}",
"tags": [
"support"
],
"type": "chat",
"variables": [
"company",
"question"
],
"version": 4
}Delete dataset item
Delete an item from its dataset, with its results in past runs.
Inputs
- Item ID
item_idtextRequired - The item's ID, such as the id of Add dataset item.
Outputs
deletedtrue/false- Always true
item_idtext- The item deleted
Example output
{
"deleted": true,
"item_id": "a1d0c6e8-3b2f-4e5a-9c7d-1f2e3d4c5b6a"
}Delete prompt
Delete one version of a prompt, or the whole prompt with every version.
Inputs
- Prompt
nametextRequired - The prompt: pick one, or type its name (with its folder, such as support/answer).
- Version
versionnumber - The version to delete. Leave blank to delete every version.At least 1.
Outputs
deletedtrue/false- Always true
nametext- The prompt
versionnumber- The version deleted; 0 when every version was
Example output
{
"deleted": true,
"name": "support-answer",
"version": 3
}Delete score
Delete a score, such as one given by mistake.
Inputs
- Score ID
score_idtextRequired - The score's ID, such as the id of Add score or List scores.
Outputs
deletedtrue/false- Always true
score_idtext- The score deleted
Example output
{
"deleted": true,
"score_id": "7f4e9a2c-0b1d-4c3e-9f8a-6b5d4c3e2f1a"
}Delete trace
Delete a trace with its observations and scores, such as when a user asks for their data to be removed. Langfuse deletes it in the background.
Inputs
- Trace ID
trace_idtextRequired - The trace's ID, such as the trace_id of Log trace or the id of a trace from List traces. It's at the end of the trace's address in Langfuse.
Outputs
deletedtrue/false- Always true: Langfuse deletes it in the background
trace_idtext- The trace deleted
Example output
{
"deleted": true,
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}Get daily usage
Get cost, tokens, traces and observations per day, for the whole project or one trace name, user, tag or environment, optionally split by model: for a daily cost report or a budget alert.
Inputs
- Since
sincedate and time - Only usage from this time on. Defaults to 7 days ago.
- Until
untildate and time - Only ones before this time. Defaults to now.
- Split by model
by_modeltrue/false - Give each model its own row per day.
- Trace name
trace_nametext - Only traces with this name.
- User
usertext - Only ones for this user, as your app names them (Langfuse's User ID).
- Tags
tagslist - Only traces with all of these tags.
- Environment
environmenttext - Only this environment, such as production.
Outputs
countnumber- How many rows
dayslist- Usage per day (and per model, when asked), the first day first
sincetext- The start of the time looked at (ISO 8601)
total_costnumber- The cost over the whole time, in US dollars
total_tokensnumber- The tokens over the whole time
total_tracesnumber- The traces over the whole time
untiltext- The end of the time looked at (ISO 8601)
Example output
{
"count": 2,
"days": [
{
"date": "2026-11-11",
"input_tokens": 1620400,
"model": "",
"observations": 4890,
"output_tokens": 301220,
"total_cost": 3.4721,
"total_tokens": 1921620,
"traces": 1204
},
{
"date": "2026-11-12",
"input_tokens": 498210,
"model": "",
"observations": 1502,
"output_tokens": 90410,
"total_cost": 1.0294,
"total_tokens": 588620,
"traces": 388
}
],
"since": "2026-11-11T00:00:00.000Z",
"total_cost": 4.5015,
"total_tokens": 2510240,
"total_traces": 1592,
"until": "2026-11-12T12:00:00.000Z"
}Get prompt
Get a prompt by label (production unless you pick another) or version, with its variables filled in, ready to send to a model, as text or chat messages, and its config.
Inputs
- Prompt
nametextRequired - The prompt: pick one, or type its name (with its folder, such as support/answer).
- Label
labeltext - The label of the version to get, such as production or staging. Defaults to production.
- Version
versionnumber - A version number to get instead of a label.At least 1.
- Variables
variablesobject - Values for the prompt's {{variables}}, such as {"question": "Why was I charged twice?"}.
Outputs
commit_messagetext- The note saved with this version
compiledtext- The prompt with the variables you gave filled in, ready to send to a model (a chat prompt as role: content lines)
compiled_messageslist- A chat prompt's messages with the variables filled in
configobject- Its config, such as the model and temperature
idtext- The prompt version's ID, for Add comment
labelslist- This version's labels, such as production and latest
linktext- A link to the prompt version in Langfuse
messageslist- A chat prompt's messages as written; empty for a text prompt
missing_variableslist- The variables it has that you didn't give
nametext- The prompt's name
prompttext- The prompt as written, with its {{variables}}; a chat prompt as role: content lines
tagslist- The prompt's tags
typetext- text or chat
variableslist- The {{variables}} the prompt has
versionnumber- The version's number
Example output
{
"commit_message": "Shorter answers",
"compiled": "system: You answer billing questions for Acme.\n\nuser: Why was I charged twice?",
"compiled_messages": [
{
"content": "You answer billing questions for Acme.",
"role": "system"
},
{
"content": "Why was I charged twice?",
"role": "user"
}
],
"config": {
"model": "gpt-4o-mini",
"temperature": 0.2
},
"id": "c01951f3-b3a4-4e3d-a748-29829e736e92",
"labels": [
"production",
"latest"
],
"link": "https://cloud.langfuse.com/project/cm8x2k1lq0001/prompts/support-answer?version=4",
"messages": [
{
"content": "You answer billing questions for {{company}}.",
"role": "system"
},
{
"content": "{{question}}",
"role": "user"
}
],
"missing_variables": [],
"name": "support-answer",
"prompt": "system: You answer billing questions for {{company}}.\n\nuser: {{question}}",
"tags": [
"support"
],
"type": "chat",
"variables": [
"company",
"question"
],
"version": 4
}Get session
Get a session (a conversation) with its traces in order, their inputs and outputs, and what it cost.
Inputs
- Session ID
session_idtextRequired - The session's ID, as your app set it.
- Since
sincedate and time - Only traces from this time on. Defaults to 30 days ago.
Outputs
first_timetext- When its first trace started (ISO 8601)
idtext- The session's ID
last_timetext- When its last trace started (ISO 8601)
linktext- A link to the session in Langfuse
total_costnumber- What it cost, in US dollars
total_tokensnumber- How many tokens it used
trace_countnumber- How many traces it has
traceslist- Its traces, the first first
user_idtext- The user it was with
Example output
{
"first_time": "2026-11-12T09:30:00.000Z",
"id": "chat-5521",
"last_time": "2026-11-12T09:30:00.000Z",
"link": "https://cloud.langfuse.com/project/cm8x2k1lq0001/sessions/chat-5521",
"total_cost": 0.00213,
"total_tokens": 812,
"trace_count": 1,
"traces": [
{
"end_time": "2026-11-12T09:30:02.350Z",
"environment": "production",
"id": "4bf92f3577b34da6a3ce929d0e0e4736",
"input": "{\"question\": \"Why was I charged twice?\"}",
"latency_seconds": 2.35,
"level": "DEFAULT",
"link": "https://cloud.langfuse.com/project/cm8x2k1lq0001/traces/4bf92f3577b34da6a3ce929d0e0e4736",
"name": "support-chat",
"observation_count": 3,
"output": "{\"answer\": \"The second charge is a hold that drops off in 3 days.\"}",
"release": "2026.11.3",
"session_id": "chat-5521",
"start_time": "2026-11-12T09:30:00.000Z",
"tags": [
"production",
"billing"
],
"total_cost": 0.00213,
"total_tokens": 812,
"user_id": "user-1842",
"version": ""
}
],
"user_id": "user-1842"
}Get trace
Get a trace with every observation in it (each step, model call, tokens and cost) and its scores.
Inputs
- Trace ID
trace_idtextRequired - The trace's ID, such as the trace_id of Log trace or the id of a trace from List traces. It's at the end of the trace's address in Langfuse.
- Started after
sincedate and time - When the trace started, or any time before. Langfuse finds an old trace faster with it.
Outputs
end_timetext- When it ended (ISO 8601)
environmenttext- Its environment, such as production or default
idtext- The trace's ID
inputtext- What went in, as text (often JSON)
latency_secondsnumber- How long it took, in seconds
leveltext- Its level: DEBUG, DEFAULT, WARNING or ERROR
linktext- A link to the trace in Langfuse
metadataobject- The trace's metadata
nametext- The trace's name, such as support-chat
observation_countnumber- How many observations (steps) it has
observationslist- Its observations, the first first
outputtext- What came out, as text (often JSON)
releasetext- Your app's release it came from; empty if none
scoreslist- Its scores
session_idtext- The session (conversation) it is part of; empty if none
start_timetext- When it started (ISO 8601)
tagslist- Its tags
total_costnumber- What its model calls cost, in US dollars
total_tokensnumber- How many tokens its model calls used
user_idtext- The user it was for, as your app named them; empty if none
versiontext- Its version; empty if none
Example output
{
"end_time": "2026-11-12T09:30:02.350Z",
"environment": "production",
"id": "4bf92f3577b34da6a3ce929d0e0e4736",
"input": "{\"question\": \"Why was I charged twice?\"}",
"latency_seconds": 2.35,
"level": "DEFAULT",
"link": "https://cloud.langfuse.com/project/cm8x2k1lq0001/traces/4bf92f3577b34da6a3ce929d0e0e4736",
"metadata": {
"plan": "pro"
},
"name": "support-chat",
"observation_count": 3,
"observations": [
{
"cost": 0.0,
"end_time": "2026-11-12T09:30:02.350Z",
"environment": "production",
"id": "00f067aa0ba902b7",
"input": "[{\"role\": \"user\", \"content\": \"Why was I charged twice?\"}]",
"input_tokens": 0,
"latency_seconds": 2.35,
"level": "DEFAULT",
"model": "",
"name": "support-chat",
"output": "The second charge is a hold that drops off in 3 days.",
"output_tokens": 0,
"parent_observation_id": "",
"prompt_name": "",
"prompt_version": "",
"session_id": "chat-5521",
"start_time": "2026-11-12T09:30:00.000Z",
"status_message": "",
"total_tokens": 0,
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"type": "SPAN",
"user_id": "user-1842"
},
{
"cost": 0.00213,
"end_time": "2026-11-12T09:30:02.300Z",
"environment": "production",
"id": "b7ad6b7169203331",
"input": "[{\"role\": \"user\", \"content\": \"Why was I charged twice?\"}]",
"input_tokens": 640,
"latency_seconds": 1.9,
"level": "DEFAULT",
"model": "gpt-4o-mini",
"name": "answer",
"output": "The second charge is a hold that drops off in 3 days.",
"output_tokens": 172,
"parent_observation_id": "00f067aa0ba902b7",
"prompt_name": "support-answer",
"prompt_version": "4",
"session_id": "chat-5521",
"start_time": "2026-11-12T09:30:00.400Z",
"status_message": "",
"total_tokens": 812,
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"type": "GENERATION",
"user_id": "user-1842"
}
],
"output": "{\"answer\": \"The second charge is a hold that drops off in 3 days.\"}",
"release": "2026.11.3",
"scores": [
{
"attached_to": "trace",
"comment": "The answer was wrong",
"config_id": "",
"data_type": "BOOLEAN",
"environment": "production",
"id": "7f4e9a2c-0b1d-4c3e-9f8a-6b5d4c3e2f1a",
"is_numeric": true,
"name": "user-feedback",
"numeric_value": 0.0,
"observation_id": "",
"session_id": "",
"source": "API",
"timestamp": "2026-11-12T09:31:10.000Z",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"value": "0"
}
],
"session_id": "chat-5521",
"start_time": "2026-11-12T09:30:00.000Z",
"tags": [
"production",
"billing"
],
"total_cost": 0.00213,
"total_tokens": 812,
"user_id": "user-1842",
"version": ""
}Label prompt version
Move labels such as production to a version of a prompt; they leave the version that had them. This is how a new version is promoted, or an old one brought back.
Inputs
- Prompt
nametextRequired - The prompt: pick one, or type its name (with its folder, such as support/answer).
- Version
versionnumberRequired - The version's number, such as the version of Create prompt version.At least 1.
- Labels
labelslistRequired - The labels to give it, such as production.
Outputs
added_labelslist- The labels moved to this version
commit_messagetext- The note saved with this version
compiledtext- The prompt with the variables you gave filled in, ready to send to a model (a chat prompt as role: content lines)
compiled_messageslist- A chat prompt's messages with the variables filled in
configobject- Its config, such as the model and temperature
idtext- The prompt version's ID, for Add comment
labelslist- This version's labels, such as production and latest
linktext- A link to the prompt version in Langfuse
messageslist- A chat prompt's messages as written; empty for a text prompt
missing_variableslist- The variables it has that you didn't give
nametext- The prompt's name
prompttext- The prompt as written, with its {{variables}}; a chat prompt as role: content lines
tagslist- The prompt's tags
typetext- text or chat
variableslist- The {{variables}} the prompt has
versionnumber- The version's number
Example output
{
"added_labels": [
"production"
],
"commit_message": "Shorter answers",
"compiled": "system: You answer billing questions for Acme.\n\nuser: Why was I charged twice?",
"compiled_messages": [
{
"content": "You answer billing questions for Acme.",
"role": "system"
},
{
"content": "Why was I charged twice?",
"role": "user"
}
],
"config": {
"model": "gpt-4o-mini",
"temperature": 0.2
},
"id": "c01951f3-b3a4-4e3d-a748-29829e736e92",
"labels": [
"production",
"latest"
],
"link": "https://cloud.langfuse.com/project/cm8x2k1lq0001/prompts/support-answer?version=4",
"messages": [
{
"content": "You answer billing questions for {{company}}.",
"role": "system"
},
{
"content": "{{question}}",
"role": "user"
}
],
"missing_variables": [],
"name": "support-answer",
"prompt": "system: You answer billing questions for {{company}}.\n\nuser: {{question}}",
"tags": [
"support"
],
"type": "chat",
"variables": [
"company",
"question"
],
"version": 4
}List comments
List comments, the newest first, on one trace, observation, session or prompt, or on every one of a kind.
Inputs
- On
object_typetext - Only comments on this kind of thing. Defaults to Trace when an ID is given.One of:
TRACE,OBSERVATION,SESSION,PROMPT. - ID
object_idtext - Only comments on this trace, observation, session or prompt.
- How many
limitnumber - The most comments to list, 1 to 100. Defaults to 50.From 1 to 100.
Outputs
commentslist- The comments, the newest first
countnumber- How many were listed
Example output
{
"comments": [
{
"author_user_id": "",
"content": "Escalated to billing: refund issued.",
"created": "2026-11-12T09:45:00.000Z",
"id": "cm8z3comm0001",
"object_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"object_type": "TRACE"
}
],
"count": 1
}List dataset items
List a dataset's active items, the newest first, with their inputs and expected outputs. Langfuse leaves archived items out.
Inputs
- Dataset
datasettextRequired - The dataset: pick one, or type its name.
- From trace
source_trace_idtext - Only items taken from this trace.
- How many
limitnumber - The most items to list, 1 to 100. Defaults to 50.From 1 to 100.
Outputs
countnumber- How many were listed
itemslist- The items, the newest first
totalnumber- How many active items the dataset has
Example output
{
"count": 1,
"items": [
{
"created": "2026-11-12T09:40:00.000Z",
"dataset_name": "billing-questions",
"expected_output": "A hold that drops off in 3 days",
"id": "a1d0c6e8-3b2f-4e5a-9c7d-1f2e3d4c5b6a",
"input": "{\"question\": \"Why was I charged twice?\"}",
"metadata": {
"topic": "billing"
},
"source_observation_id": "",
"source_trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"status": "ACTIVE",
"updated": "2026-11-12T09:40:00.000Z"
}
],
"total": 1
}List dataset runs
List a dataset's runs (experiments), the latest first, with how many items each ran and their scores.
Inputs
- Dataset
datasettextRequired - The dataset: pick one, or type its name.
- Run name
run_nametext - Only the run with this name.
- Since
sincedate and time - Only runs from this time on. Defaults to 90 days ago.
- How many
limitnumber - The most runs to list, 1 to 100. Defaults to 25.From 1 to 100.
Outputs
countnumber- How many runs were listed
dataset_idtext- The dataset's ID
dataset_nametext- The dataset's name
runslist- Its runs (experiments), the latest first
Example output
{
"count": 1,
"dataset_id": "cm8z2data0001",
"dataset_name": "billing-questions",
"runs": [
{
"description": "Shorter answers prompt",
"end_time": "2026-11-11T16:04:31.000Z",
"id": "run-gpt-4o-mini-2026-11-11",
"item_count": 120,
"item_scores": [
"accuracy=0.91"
],
"link": "https://cloud.langfuse.com/project/cm8x2k1lq0001/datasets/cm8z2data0001/runs/run-gpt-4o-mini-2026-11-11",
"metadata": {
"model": "gpt-4o-mini"
},
"name": "gpt-4o-mini 2026-11-11",
"scores": [],
"start_time": "2026-11-11T16:00:00.000Z"
}
]
}List observations
List recent observations, the latest first: generations of a model, the steps of one trace, or the ones that went wrong, with their tokens and cost.
Inputs
- Type
observation_typetext - Only observations of this type, such as Generation for model calls.One of:
SPAN,GENERATION,EVENT,AGENT,TOOL,CHAIN,RETRIEVER,EVALUATOR,EMBEDDING,GUARDRAIL. - Name
nametext - Only observations with this name.
- Level
leveltext - Only observations at this level, such as Error.One of:
DEBUG,DEFAULT,WARNING,ERROR. - Trace ID
trace_idtext - Only observations in this trace.
- Model
modeltext - Only generations of this model, such as gpt-4o.
- User
usertext - Only ones for this user, as your app names them (Langfuse's User ID).
- Session ID
session_idtext - Only ones in this session (conversation).
- Since
sincedate and time - Only ones from this time on. Defaults to 7 days ago.
- Until
untildate and time - Only ones before this time. Defaults to now.
- How many
limitnumber - The most observations to list, 1 to 100. Defaults to 25.From 1 to 100.
Outputs
countnumber- How many were listed
observationslist- The observations, the latest first
sincetext- The start of the time looked at (ISO 8601)
total_costnumber- What the listed ones cost together, in US dollars
untiltext- The end of the time looked at (ISO 8601)
Example output
{
"count": 1,
"observations": [
{
"cost": 0.00213,
"end_time": "2026-11-12T09:30:02.300Z",
"environment": "production",
"id": "b7ad6b7169203331",
"input": "[{\"role\": \"user\", \"content\": \"Why was I charged twice?\"}]",
"input_tokens": 640,
"latency_seconds": 1.9,
"level": "DEFAULT",
"model": "gpt-4o-mini",
"name": "answer",
"output": "The second charge is a hold that drops off in 3 days.",
"output_tokens": 172,
"parent_observation_id": "00f067aa0ba902b7",
"prompt_name": "support-answer",
"prompt_version": "4",
"session_id": "chat-5521",
"start_time": "2026-11-12T09:30:00.400Z",
"status_message": "",
"total_tokens": 812,
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"type": "GENERATION",
"user_id": "user-1842"
}
],
"since": "2026-11-05T09:35:00.000Z",
"total_cost": 0.00213,
"until": "2026-11-12T09:35:00.000Z"
}List prompts
List prompts with their versions, labels and tags.
Inputs
- Name
nametext - Only the prompt with this name.
- Label
labeltext - Only prompts with a version that has this label, such as production.
- Tag
tagtext - Only prompts with this tag.
- How many
limitnumber - The most prompts to list, 1 to 100. Defaults to 50.From 1 to 100.
Outputs
countnumber- How many were listed
promptslist- The prompts, by name
Example output
{
"count": 1,
"prompts": [
{
"labels": [
"production",
"latest",
"staging"
],
"last_updated": "2026-11-10T14:02:11.000Z",
"latest_version": 4,
"name": "support-answer",
"tags": [
"support"
],
"type": "chat",
"versions": [
1,
2,
3,
4
]
}
]
}List score configs
List the project's score configs: each score's name, type, allowed range or categories.
Inputs
- Include archived
include_archivedtrue/false - Also list archived configs.
- How many
limitnumber - The most score configs to list, 1 to 100. Defaults to 50.From 1 to 100.
Outputs
countnumber- How many were listed
score_configslist- The score configs
Example output
{
"count": 2,
"score_configs": [
{
"archived": false,
"categories": [],
"data_type": "NUMERIC",
"description": "How much the answer helped",
"id": "cm8z1score0002",
"max_value": "1",
"min_value": "0",
"name": "helpfulness"
},
{
"archived": false,
"categories": [
"friendly=1",
"neutral=0",
"rude=-1"
],
"data_type": "CATEGORICAL",
"description": "",
"id": "cm8z1score0003",
"max_value": "",
"min_value": "",
"name": "tone"
}
]
}List scores
List recent scores, the latest first, by name, trace, session, source and value range, such as every low helpfulness score this week, with their average.
Inputs
- Score name
nametext - Only scores with this name; several separated by commas.
- Trace ID
trace_idtext - Only scores of this trace.
- Observation ID
observation_idtext - Only scores of this observation (give its trace too).
- Session ID
session_idtext - Only ones in this session (conversation).
- Source
sourcetext - Only scores from here: the API, people annotating, or evaluators.One of:
API,ANNOTATION,EVAL(Evaluation). - Type
data_typetext - Only scores of this kind.One of:
NUMERIC(Number),BOOLEAN(True or false),CATEGORICAL(Category),TEXT. - At least
min_valuenumber - Only number scores of this value or more.
- At most
max_valuenumber - Only number scores of this value or less, such as 0.5 for low scores.
- Since
sincedate and time - Only scores from this time on. Defaults to 7 days ago.
- Until
untildate and time - Only ones before this time. Defaults to now.
- How many
limitnumber - The most scores to list, 1 to 100. Defaults to 25.From 1 to 100.
Outputs
averagenumber- The average of the number and true/false values listed
countnumber- How many were listed
scoreslist- The scores, the latest first
sincetext- The start of the time looked at (ISO 8601)
untiltext- The end of the time looked at (ISO 8601)
Example output
{
"average": 0.0,
"count": 1,
"scores": [
{
"attached_to": "trace",
"comment": "The answer was wrong",
"config_id": "",
"data_type": "BOOLEAN",
"environment": "production",
"id": "7f4e9a2c-0b1d-4c3e-9f8a-6b5d4c3e2f1a",
"is_numeric": true,
"name": "user-feedback",
"numeric_value": 0.0,
"observation_id": "",
"session_id": "",
"source": "API",
"timestamp": "2026-11-12T09:31:10.000Z",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"value": "0"
}
],
"since": "2026-11-05T09:35:00.000Z",
"until": "2026-11-12T09:35:00.000Z"
}List traces
List recent traces, the latest first, by name, user, session, tags and environment, with each one's input, output, time taken, cost and tokens.
Inputs
- Trace name
nametext - Only traces with this name, such as support-chat.
- User
usertext - Only ones for this user, as your app names them (Langfuse's User ID).
- Session ID
session_idtext - Only ones in this session (conversation).
- Tags
tagslist - Only traces with all of these tags.
- Environment
environmenttext - Only traces from this environment, such as production.
- Since
sincedate and time - Only traces from this time on. Defaults to 7 days ago.
- Until
untildate and time - Only ones before this time. Defaults to now.
- How many
limitnumber - The most traces to list, 1 to 100. Defaults to 25.From 1 to 100.
Outputs
countnumber- How many traces were listed
sincetext- The start of the time looked at (ISO 8601)
traceslist- The traces, the latest first
untiltext- The end of the time looked at (ISO 8601)
Example output
{
"count": 1,
"since": "2026-11-05T09:35:00.000Z",
"traces": [
{
"end_time": "2026-11-12T09:30:02.350Z",
"environment": "production",
"id": "4bf92f3577b34da6a3ce929d0e0e4736",
"input": "{\"question\": \"Why was I charged twice?\"}",
"latency_seconds": 2.35,
"level": "DEFAULT",
"link": "https://cloud.langfuse.com/project/cm8x2k1lq0001/traces/4bf92f3577b34da6a3ce929d0e0e4736",
"name": "support-chat",
"observation_count": 3,
"output": "{\"answer\": \"The second charge is a hold that drops off in 3 days.\"}",
"release": "2026.11.3",
"session_id": "chat-5521",
"start_time": "2026-11-12T09:30:00.000Z",
"tags": [
"production",
"billing"
],
"total_cost": 0.00213,
"total_tokens": 812,
"user_id": "user-1842",
"version": ""
}
],
"until": "2026-11-12T09:35:00.000Z"
}Log trace
Log a trace to Langfuse, such as a model call a workflow made: one span or generation with its input, output, user, session, tags and, for a generation, model, tokens and cost.
Inputs
- Name
nametextRequired - What the trace is, such as support-chat or nightly-summary.
- Input
inputtext - What went in, such as the user's question or {"messages": [...]}. JSON is kept as JSON.
- Output
outputtext - What came out, such as the model's answer. JSON is kept as JSON.
- User
usertext - The user it was for, as your app names them.
- Session ID
session_idtext - The session (conversation) it is part of, to group traces.
- Tags
tagslist - Tags to find it by.
- Metadata
metadataobject - More about it, such as {"customer": "acme"}.
- Environment
environmenttext - Its environment, such as production or staging: lowercase letters, numbers and dashes.
- Release
releasetext - Your app's release, such as 2026.11.3.
- Version
versiontext - The version of what ran, such as v2.
- Type
observation_typetext - What it records. Defaults to Generation when a model is given, otherwise Span.One of:
span,generation,event,agent,tool,retriever. - Model
modeltext - For a generation: the model called, such as gpt-4o-mini. Langfuse works out the cost from it and the tokens when it knows the model.
- Input tokens
input_tokensnumber - For a generation: tokens sent to the model.At least 0.
- Output tokens
output_tokensnumber - For a generation: tokens the model wrote.At least 0.
- Cost (USD)
costnumber - For a generation: what it cost in US dollars, such as 0.0021. Leave blank to let Langfuse work it out.At least 0.
- Prompt
prompt_nametext - The Langfuse prompt it used, to link the two.
- Prompt version
prompt_versionnumber - That prompt's version, such as the version of Get prompt.At least 1.
- Level
leveltext - How it went: Error or Warning marks it in Langfuse. Defaults to Default.One of:
DEBUG,DEFAULT,WARNING,ERROR. Default:DEFAULT. - Status message
status_messagetext - What to say about how it went, such as the error.
- Start time
start_timedate and time - When it started. Defaults to now.
- End time
end_timedate and time - When it ended. Defaults to the start time.
Outputs
linktext- A link to the trace in Langfuse
nametext- The trace's name
observation_idtext- The ID of the observation logged
observation_typetext- What was logged: SPAN, GENERATION, EVENT and so on
session_idtext- The session it is part of
tagslist- Its tags
trace_idtext- The trace's ID
user_idtext- The user it was for
Example output
{
"link": "https://cloud.langfuse.com/project/cm8x2k1lq0001/traces/4bf92f3577b34da6a3ce929d0e0e4736",
"name": "support-chat",
"observation_id": "00f067aa0ba902b7",
"observation_type": "GENERATION",
"session_id": "chat-5521",
"tags": [
"production"
],
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"user_id": "user-1842"
}