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

ActionWhat it does
Add commentAdd a comment to a trace, observation, session or prompt, such as what a reviewer found or what was done about it.
Add dataset itemAdd 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 traceAdd 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 scoreScore 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 datasetCreate a dataset to collect test cases in, such as questions with their right answers.
Create prompt versionSave 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 itemDelete an item from its dataset, with its results in past runs.
Delete promptDelete one version of a prompt, or the whole prompt with every version.
Delete scoreDelete a score, such as one given by mistake.
Delete traceDelete a trace with its observations and scores, such as when a user asks for their data to be removed.
Get daily usageGet 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 promptGet 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 sessionGet a session (a conversation) with its traces in order, their inputs and outputs, and what it cost.
Get traceGet a trace with every observation in it (each step, model call, tokens and cost) and its scores.
Label prompt versionMove labels such as production to a version of a prompt; they leave the version that had them.
List commentsList comments, the newest first, on one trace, observation, session or prompt, or on every one of a kind.
List dataset itemsList a dataset's active items, the newest first, with their inputs and expected outputs.
List dataset runsList a dataset's runs (experiments), the latest first, with how many items each ran and their scores.
List observationsList 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 promptsList prompts with their versions, labels and tags.
List score configsList the project's score configs: each score's name, type, allowed range or categories.
List scoresList 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 tracesList recent traces, the latest first, by name, user, session, tags and environment, with each one's input, output, time taken, cost and tokens.
Log traceLog 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

Onobject_typetext
What to comment on. Defaults to Trace.One of: TRACE, OBSERVATION, SESSION, PROMPT. Default: TRACE.
IDobject_idtextRequired
The ID of the trace, observation or session (or the prompt's ID).
CommentcontenttextRequired
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

DatasetdatasettextRequired
The dataset: pick one, or type its name.
InputinputtextRequired
What the test gives your app, such as {"question": "Why was I charged twice?"}.
Expected outputexpected_outputtext
The right answer.
Metadatametadataobject
More about it, such as {"topic": "billing"}.
From tracesource_trace_idtext
The trace it was taken from, to link the two.
From observationsource_observation_idtext
The observation in that trace it was taken from.
Item IDitem_idtext
An ID for it, so adding it again changes it rather than adding another. Leave blank for a new one.
Statusstatustext
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 IDtrace_idtextRequired
The trace to add to: the trace_id of Log trace.
NamenametextRequired
What this step was, such as retrieve-docs or call-model.
Typeobservation_typetext
What it records. Defaults to Generation when a model is given, otherwise Span.One of: span, generation, event, agent, tool, retriever.
Inside observationparent_observation_idtext
The observation to put it inside, such as the observation_id of Log trace. Defaults to the trace's first.
Inputinputtext
What went in, such as the user's question or {"messages": [...]}. JSON is kept as JSON.
Outputoutputtext
What came out, such as the model's answer. JSON is kept as JSON.
Modelmodeltext
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 tokensinput_tokensnumber
For a generation: tokens sent to the model.At least 0.
Output tokensoutput_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.
Promptprompt_nametext
The Langfuse prompt it used, to link the two.
Prompt versionprompt_versionnumber
That prompt's version, such as the version of Get prompt.At least 1.
Levelleveltext
How it went: Error or Warning marks it in Langfuse. Defaults to Default.One of: DEBUG, DEFAULT, WARNING, ERROR. Default: DEFAULT.
Status messagestatus_messagetext
What to say about how it went, such as the error.
Metadatametadataobject
More about it, such as {"source": "faq"}.
Start timestart_timedate and time
When it started. Defaults to now.
End timeend_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 namenametextRequired
What it measures, such as helpfulness or user-feedback.
ValuevaluetextRequired
The score: a number such as 0.8, true or false, or a category such as good.
Trace IDtrace_idtext
The trace to score.
Observation IDobservation_idtext
An observation in that trace to score instead of the whole trace.
Session IDsession_idtext
A session to score, instead of a trace.
Typedata_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 configconfig_idtext
A score config it follows, which sets its name's type and allowed values.
Commentcommenttext
Why it got this score.
Metadatametadataobject
More about it, such as {"reviewer": "ana"}.
Environmentenvironmenttext
Its environment, such as production.
Score IDscore_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

NamenametextRequired
The dataset's name, such as billing-questions.
Descriptiondescriptiontext
What it holds.
Metadatametadataobject
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

PromptnametextRequired
The prompt's name: pick one for a new version, or type a new name.
PromptprompttextRequired
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}}."}].
Typeprompt_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.
Labelslabelslist
Labels for this version, such as staging or production. A label moves here from the version that had it.
Tagstagslist
Tags for the prompt.
Configconfigobject
Settings for it, such as {"model": "gpt-4o-mini", "temperature": 0}.
Change notecommit_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 IDitem_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

PromptnametextRequired
The prompt: pick one, or type its name (with its folder, such as support/answer).
Versionversionnumber
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 IDscore_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 IDtrace_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

Sincesincedate and time
Only usage from this time on. Defaults to 7 days ago.
Untiluntildate and time
Only ones before this time. Defaults to now.
Split by modelby_modeltrue/false
Give each model its own row per day.
Trace nametrace_nametext
Only traces with this name.
Userusertext
Only ones for this user, as your app names them (Langfuse's User ID).
Tagstagslist
Only traces with all of these tags.
Environmentenvironmenttext
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

PromptnametextRequired
The prompt: pick one, or type its name (with its folder, such as support/answer).
Labellabeltext
The label of the version to get, such as production or staging. Defaults to production.
Versionversionnumber
A version number to get instead of a label.At least 1.
Variablesvariablesobject
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 IDsession_idtextRequired
The session's ID, as your app set it.
Sincesincedate 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 IDtrace_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 aftersincedate 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

PromptnametextRequired
The prompt: pick one, or type its name (with its folder, such as support/answer).
VersionversionnumberRequired
The version's number, such as the version of Create prompt version.At least 1.
LabelslabelslistRequired
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

Onobject_typetext
Only comments on this kind of thing. Defaults to Trace when an ID is given.One of: TRACE, OBSERVATION, SESSION, PROMPT.
IDobject_idtext
Only comments on this trace, observation, session or prompt.
How manylimitnumber
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

DatasetdatasettextRequired
The dataset: pick one, or type its name.
From tracesource_trace_idtext
Only items taken from this trace.
How manylimitnumber
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

DatasetdatasettextRequired
The dataset: pick one, or type its name.
Run namerun_nametext
Only the run with this name.
Sincesincedate and time
Only runs from this time on. Defaults to 90 days ago.
How manylimitnumber
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

Typeobservation_typetext
Only observations of this type, such as Generation for model calls.One of: SPAN, GENERATION, EVENT, AGENT, TOOL, CHAIN, RETRIEVER, EVALUATOR, EMBEDDING, GUARDRAIL.
Namenametext
Only observations with this name.
Levelleveltext
Only observations at this level, such as Error.One of: DEBUG, DEFAULT, WARNING, ERROR.
Trace IDtrace_idtext
Only observations in this trace.
Modelmodeltext
Only generations of this model, such as gpt-4o.
Userusertext
Only ones for this user, as your app names them (Langfuse's User ID).
Session IDsession_idtext
Only ones in this session (conversation).
Sincesincedate and time
Only ones from this time on. Defaults to 7 days ago.
Untiluntildate and time
Only ones before this time. Defaults to now.
How manylimitnumber
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

Namenametext
Only the prompt with this name.
Labellabeltext
Only prompts with a version that has this label, such as production.
Tagtagtext
Only prompts with this tag.
How manylimitnumber
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 archivedinclude_archivedtrue/false
Also list archived configs.
How manylimitnumber
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 namenametext
Only scores with this name; several separated by commas.
Trace IDtrace_idtext
Only scores of this trace.
Observation IDobservation_idtext
Only scores of this observation (give its trace too).
Session IDsession_idtext
Only ones in this session (conversation).
Sourcesourcetext
Only scores from here: the API, people annotating, or evaluators.One of: API, ANNOTATION, EVAL (Evaluation).
Typedata_typetext
Only scores of this kind.One of: NUMERIC (Number), BOOLEAN (True or false), CATEGORICAL (Category), TEXT.
At leastmin_valuenumber
Only number scores of this value or more.
At mostmax_valuenumber
Only number scores of this value or less, such as 0.5 for low scores.
Sincesincedate and time
Only scores from this time on. Defaults to 7 days ago.
Untiluntildate and time
Only ones before this time. Defaults to now.
How manylimitnumber
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 namenametext
Only traces with this name, such as support-chat.
Userusertext
Only ones for this user, as your app names them (Langfuse's User ID).
Session IDsession_idtext
Only ones in this session (conversation).
Tagstagslist
Only traces with all of these tags.
Environmentenvironmenttext
Only traces from this environment, such as production.
Sincesincedate and time
Only traces from this time on. Defaults to 7 days ago.
Untiluntildate and time
Only ones before this time. Defaults to now.
How manylimitnumber
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

NamenametextRequired
What the trace is, such as support-chat or nightly-summary.
Inputinputtext
What went in, such as the user's question or {"messages": [...]}. JSON is kept as JSON.
Outputoutputtext
What came out, such as the model's answer. JSON is kept as JSON.
Userusertext
The user it was for, as your app names them.
Session IDsession_idtext
The session (conversation) it is part of, to group traces.
Tagstagslist
Tags to find it by.
Metadatametadataobject
More about it, such as {"customer": "acme"}.
Environmentenvironmenttext
Its environment, such as production or staging: lowercase letters, numbers and dashes.
Releasereleasetext
Your app's release, such as 2026.11.3.
Versionversiontext
The version of what ran, such as v2.
Typeobservation_typetext
What it records. Defaults to Generation when a model is given, otherwise Span.One of: span, generation, event, agent, tool, retriever.
Modelmodeltext
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 tokensinput_tokensnumber
For a generation: tokens sent to the model.At least 0.
Output tokensoutput_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.
Promptprompt_nametext
The Langfuse prompt it used, to link the two.
Prompt versionprompt_versionnumber
That prompt's version, such as the version of Get prompt.At least 1.
Levelleveltext
How it went: Error or Warning marks it in Langfuse. Defaults to Default.One of: DEBUG, DEFAULT, WARNING, ERROR. Default: DEFAULT.
Status messagestatus_messagetext
What to say about how it went, such as the error.
Start timestart_timedate and time
When it started. Defaults to now.
End timeend_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"
}

On this page