# Langfuse

> 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.

App · 24 actions. Web page: https://docs.lodol.com/docs/integrations/langfuse

## Actions

### 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_type`, text): What to comment on. Defaults to Trace. One of: `TRACE`, `OBSERVATION`, `SESSION`, `PROMPT`. Default: `TRACE`.
- ID (`object_id`, text, required): The ID of the trace, observation or session (or the prompt's ID).
- Comment (`content`, text, required): What it says, up to 5,000 characters. Markdown works.

**Outputs**

- `content` (text): What it says
- `id` (text): The comment's ID
- `object_id` (text): The ID of what it is on
- `object_type` (text): What it is on: TRACE, OBSERVATION, SESSION or PROMPT

**Example output**

```json
{
  "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 (`dataset`, text, required): The dataset: pick one, or type its name.
- Input (`input`, text, required): What the test gives your app, such as {"question": "Why was I charged twice?"}.
- Expected output (`expected_output`, text): The right answer.
- Metadata (`metadata`, object): More about it, such as {"topic": "billing"}.
- From trace (`source_trace_id`, text): The trace it was taken from, to link the two.
- From observation (`source_observation_id`, text): The observation in that trace it was taken from.
- Item ID (`item_id`, text): An ID for it, so adding it again changes it rather than adding another. Leave blank for a new one.
- Status (`status`, text): Active items are used in runs; archived ones aren't. Defaults to Active. One of: `ACTIVE`, `ARCHIVED`. Default: `ACTIVE`.

**Outputs**

- `created` (text): When it was added (ISO 8601)
- `dataset_name` (text): The dataset it is in
- `expected_output` (text): What the right answer is, as text
- `id` (text): The item's ID
- `input` (text): Its input, as text (often JSON)
- `metadata` (object): Its metadata
- `source_observation_id` (text): The observation it was made from
- `source_trace_id` (text): The trace it was made from; empty if none
- `status` (text): ACTIVE or ARCHIVED
- `updated` (text): When it was last changed (ISO 8601)

**Example output**

```json
{
  "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_id`, text, required): The trace to add to: the trace_id of Log trace.
- Name (`name`, text, required): What this step was, such as retrieve-docs or call-model.
- Type (`observation_type`, text): 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_id`, text): The observation to put it inside, such as the observation_id of Log trace. Defaults to the trace's first.
- Input (`input`, text): What went in, such as the user's question or {"messages": [...]}. JSON is kept as JSON.
- Output (`output`, text): What came out, such as the model's answer. JSON is kept as JSON.
- Model (`model`, text): 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_tokens`, number): For a generation: tokens sent to the model. At least 0.
- Output tokens (`output_tokens`, number): For a generation: tokens the model wrote. At least 0.
- Cost (USD) (`cost`, number): 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_name`, text): The Langfuse prompt it used, to link the two.
- Prompt version (`prompt_version`, number): That prompt's version, such as the version of Get prompt. At least 1.
- Level (`level`, text): How it went: Error or Warning marks it in Langfuse. Defaults to Default. One of: `DEBUG`, `DEFAULT`, `WARNING`, `ERROR`. Default: `DEFAULT`.
- Status message (`status_message`, text): What to say about how it went, such as the error.
- Metadata (`metadata`, object): More about it, such as {"source": "faq"}.
- Start time (`start_time`, date and time): When it started. Defaults to now.
- End time (`end_time`, date and time): When it ended. Defaults to the start time.

**Outputs**

- `link` (text): A link to the trace in Langfuse
- `name` (text): Its name
- `observation_id` (text): The new observation's ID
- `observation_type` (text): What it is: SPAN, GENERATION, EVENT and so on
- `parent_observation_id` (text): The observation it was put inside
- `trace_id` (text): The trace it was added to

**Example output**

```json
{
  "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 (`name`, text, required): What it measures, such as helpfulness or user-feedback.
- Value (`value`, text, required): The score: a number such as 0.8, true or false, or a category such as good.
- Trace ID (`trace_id`, text): The trace to score.
- Observation ID (`observation_id`, text): An observation in that trace to score instead of the whole trace.
- Session ID (`session_id`, text): A session to score, instead of a trace.
- Type (`data_type`, text): 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_id`, text): A score config it follows, which sets its name's type and allowed values.
- Comment (`comment`, text): Why it got this score.
- Metadata (`metadata`, object): More about it, such as {"reviewer": "ana"}.
- Environment (`environment`, text): Its environment, such as production.
- Score ID (`score_id`, text): An ID for it, so sending it again changes it rather than adding another. Leave blank for a new one.

**Outputs**

- `accepted` (true/false): Whether Langfuse accepted it
- `data_type` (text): NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or FROM_CONFIG
- `id` (text): The score's ID, for Delete score
- `name` (text): What it measures
- `observation_id` (text): The observation it scores
- `session_id` (text): The session it scores
- `trace_id` (text): The trace it scores
- `value` (text): The value sent

**Example output**

```json
{
  "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 (`name`, text, required): The dataset's name, such as billing-questions.
- Description (`description`, text): What it holds.
- Metadata (`metadata`, object): More about it, such as {"owner": "ml-team"}.

**Outputs**

- `created` (text): When it was made (ISO 8601)
- `description` (text): Its description
- `id` (text): The dataset's ID
- `link` (text): A link to the dataset in Langfuse
- `metadata` (object): Its metadata
- `name` (text): Its name
- `updated` (text): When it was last changed (ISO 8601)

**Example output**

```json
{
  "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 (`name`, text, required): The prompt's name: pick one for a new version, or type a new name.
- Prompt (`prompt`, text, required): 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_type`, text): 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 (`labels`, list): Labels for this version, such as staging or production. A label moves here from the version that had it.
- Tags (`tags`, list): Tags for the prompt.
- Config (`config`, object): Settings for it, such as {"model": "gpt-4o-mini", "temperature": 0}.
- Change note (`commit_message`, text): What changed in this version.

**Outputs**

- `commit_message` (text): The note saved with this version
- `compiled` (text): The prompt with the variables you gave filled in, ready to send to a model (a chat prompt as role: content lines)
- `compiled_messages` (list): A chat prompt's messages with the variables filled in
- `config` (object): Its config, such as the model and temperature
- `id` (text): The prompt version's ID, for Add comment
- `labels` (list): This version's labels, such as production and latest
- `link` (text): A link to the prompt version in Langfuse
- `messages` (list): A chat prompt's messages as written; empty for a text prompt
- `missing_variables` (list): The variables it has that you didn't give
- `name` (text): The prompt's name
- `prompt` (text): The prompt as written, with its {{variables}}; a chat prompt as role: content lines
- `tags` (list): The prompt's tags
- `type` (text): text or chat
- `variables` (list): The {{variables}} the prompt has
- `version` (number): The version's number

**Example output**

```json
{
  "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_id`, text, required): The item's ID, such as the id of Add dataset item.

**Outputs**

- `deleted` (true/false): Always true
- `item_id` (text): The item deleted

**Example output**

```json
{
  "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 (`name`, text, required): The prompt: pick one, or type its name (with its folder, such as support/answer).
- Version (`version`, number): The version to delete. Leave blank to delete every version. At least 1.

**Outputs**

- `deleted` (true/false): Always true
- `name` (text): The prompt
- `version` (number): The version deleted; 0 when every version was

**Example output**

```json
{
  "deleted": true,
  "name": "support-answer",
  "version": 3
}
```

### Delete score

Delete a score, such as one given by mistake.

**Inputs**

- Score ID (`score_id`, text, required): The score's ID, such as the id of Add score or List scores.

**Outputs**

- `deleted` (true/false): Always true
- `score_id` (text): The score deleted

**Example output**

```json
{
  "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_id`, text, required): 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**

- `deleted` (true/false): Always true: Langfuse deletes it in the background
- `trace_id` (text): The trace deleted

**Example output**

```json
{
  "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 (`since`, date and time): Only usage from this time on. Defaults to 7 days ago.
- Until (`until`, date and time): Only ones before this time. Defaults to now.
- Split by model (`by_model`, true/false): Give each model its own row per day.
- Trace name (`trace_name`, text): Only traces with this name.
- User (`user`, text): Only ones for this user, as your app names them (Langfuse's User ID).
- Tags (`tags`, list): Only traces with all of these tags.
- Environment (`environment`, text): Only this environment, such as production.

**Outputs**

- `count` (number): How many rows
- `days` (list): Usage per day (and per model, when asked), the first day first
- `since` (text): The start of the time looked at (ISO 8601)
- `total_cost` (number): The cost over the whole time, in US dollars
- `total_tokens` (number): The tokens over the whole time
- `total_traces` (number): The traces over the whole time
- `until` (text): The end of the time looked at (ISO 8601)

**Example output**

```json
{
  "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 (`name`, text, required): The prompt: pick one, or type its name (with its folder, such as support/answer).
- Label (`label`, text): The label of the version to get, such as production or staging. Defaults to production.
- Version (`version`, number): A version number to get instead of a label. At least 1.
- Variables (`variables`, object): Values for the prompt's {{variables}}, such as {"question": "Why was I charged twice?"}.

**Outputs**

- `commit_message` (text): The note saved with this version
- `compiled` (text): The prompt with the variables you gave filled in, ready to send to a model (a chat prompt as role: content lines)
- `compiled_messages` (list): A chat prompt's messages with the variables filled in
- `config` (object): Its config, such as the model and temperature
- `id` (text): The prompt version's ID, for Add comment
- `labels` (list): This version's labels, such as production and latest
- `link` (text): A link to the prompt version in Langfuse
- `messages` (list): A chat prompt's messages as written; empty for a text prompt
- `missing_variables` (list): The variables it has that you didn't give
- `name` (text): The prompt's name
- `prompt` (text): The prompt as written, with its {{variables}}; a chat prompt as role: content lines
- `tags` (list): The prompt's tags
- `type` (text): text or chat
- `variables` (list): The {{variables}} the prompt has
- `version` (number): The version's number

**Example output**

```json
{
  "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_id`, text, required): The session's ID, as your app set it.
- Since (`since`, date and time): Only traces from this time on. Defaults to 30 days ago.

**Outputs**

- `first_time` (text): When its first trace started (ISO 8601)
- `id` (text): The session's ID
- `last_time` (text): When its last trace started (ISO 8601)
- `link` (text): A link to the session in Langfuse
- `total_cost` (number): What it cost, in US dollars
- `total_tokens` (number): How many tokens it used
- `trace_count` (number): How many traces it has
- `traces` (list): Its traces, the first first
- `user_id` (text): The user it was with

**Example output**

```json
{
  "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_id`, text, required): 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 (`since`, date and time): When the trace started, or any time before. Langfuse finds an old trace faster with it.

**Outputs**

- `end_time` (text): When it ended (ISO 8601)
- `environment` (text): Its environment, such as production or default
- `id` (text): The trace's ID
- `input` (text): What went in, as text (often JSON)
- `latency_seconds` (number): How long it took, in seconds
- `level` (text): Its level: DEBUG, DEFAULT, WARNING or ERROR
- `link` (text): A link to the trace in Langfuse
- `metadata` (object): The trace's metadata
- `name` (text): The trace's name, such as support-chat
- `observation_count` (number): How many observations (steps) it has
- `observations` (list): Its observations, the first first
- `output` (text): What came out, as text (often JSON)
- `release` (text): Your app's release it came from; empty if none
- `scores` (list): Its scores
- `session_id` (text): The session (conversation) it is part of; empty if none
- `start_time` (text): When it started (ISO 8601)
- `tags` (list): Its tags
- `total_cost` (number): What its model calls cost, in US dollars
- `total_tokens` (number): How many tokens its model calls used
- `user_id` (text): The user it was for, as your app named them; empty if none
- `version` (text): Its version; empty if none

**Example output**

```json
{
  "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 (`name`, text, required): The prompt: pick one, or type its name (with its folder, such as support/answer).
- Version (`version`, number, required): The version's number, such as the version of Create prompt version. At least 1.
- Labels (`labels`, list, required): The labels to give it, such as production.

**Outputs**

- `added_labels` (list): The labels moved to this version
- `commit_message` (text): The note saved with this version
- `compiled` (text): The prompt with the variables you gave filled in, ready to send to a model (a chat prompt as role: content lines)
- `compiled_messages` (list): A chat prompt's messages with the variables filled in
- `config` (object): Its config, such as the model and temperature
- `id` (text): The prompt version's ID, for Add comment
- `labels` (list): This version's labels, such as production and latest
- `link` (text): A link to the prompt version in Langfuse
- `messages` (list): A chat prompt's messages as written; empty for a text prompt
- `missing_variables` (list): The variables it has that you didn't give
- `name` (text): The prompt's name
- `prompt` (text): The prompt as written, with its {{variables}}; a chat prompt as role: content lines
- `tags` (list): The prompt's tags
- `type` (text): text or chat
- `variables` (list): The {{variables}} the prompt has
- `version` (number): The version's number

**Example output**

```json
{
  "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_type`, text): Only comments on this kind of thing. Defaults to Trace when an ID is given. One of: `TRACE`, `OBSERVATION`, `SESSION`, `PROMPT`.
- ID (`object_id`, text): Only comments on this trace, observation, session or prompt.
- How many (`limit`, number): The most comments to list, 1 to 100. Defaults to 50. From 1 to 100.

**Outputs**

- `comments` (list): The comments, the newest first
- `count` (number): How many were listed

**Example output**

```json
{
  "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 (`dataset`, text, required): The dataset: pick one, or type its name.
- From trace (`source_trace_id`, text): Only items taken from this trace.
- How many (`limit`, number): The most items to list, 1 to 100. Defaults to 50. From 1 to 100.

**Outputs**

- `count` (number): How many were listed
- `items` (list): The items, the newest first
- `total` (number): How many active items the dataset has

**Example output**

```json
{
  "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 (`dataset`, text, required): The dataset: pick one, or type its name.
- Run name (`run_name`, text): Only the run with this name.
- Since (`since`, date and time): Only runs from this time on. Defaults to 90 days ago.
- How many (`limit`, number): The most runs to list, 1 to 100. Defaults to 25. From 1 to 100.

**Outputs**

- `count` (number): How many runs were listed
- `dataset_id` (text): The dataset's ID
- `dataset_name` (text): The dataset's name
- `runs` (list): Its runs (experiments), the latest first

**Example output**

```json
{
  "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_type`, text): Only observations of this type, such as Generation for model calls. One of: `SPAN`, `GENERATION`, `EVENT`, `AGENT`, `TOOL`, `CHAIN`, `RETRIEVER`, `EVALUATOR`, `EMBEDDING`, `GUARDRAIL`.
- Name (`name`, text): Only observations with this name.
- Level (`level`, text): Only observations at this level, such as Error. One of: `DEBUG`, `DEFAULT`, `WARNING`, `ERROR`.
- Trace ID (`trace_id`, text): Only observations in this trace.
- Model (`model`, text): Only generations of this model, such as gpt-4o.
- User (`user`, text): Only ones for this user, as your app names them (Langfuse's User ID).
- Session ID (`session_id`, text): Only ones in this session (conversation).
- Since (`since`, date and time): Only ones from this time on. Defaults to 7 days ago.
- Until (`until`, date and time): Only ones before this time. Defaults to now.
- How many (`limit`, number): The most observations to list, 1 to 100. Defaults to 25. From 1 to 100.

**Outputs**

- `count` (number): How many were listed
- `observations` (list): The observations, the latest first
- `since` (text): The start of the time looked at (ISO 8601)
- `total_cost` (number): What the listed ones cost together, in US dollars
- `until` (text): The end of the time looked at (ISO 8601)

**Example output**

```json
{
  "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 (`name`, text): Only the prompt with this name.
- Label (`label`, text): Only prompts with a version that has this label, such as production.
- Tag (`tag`, text): Only prompts with this tag.
- How many (`limit`, number): The most prompts to list, 1 to 100. Defaults to 50. From 1 to 100.

**Outputs**

- `count` (number): How many were listed
- `prompts` (list): The prompts, by name

**Example output**

```json
{
  "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_archived`, true/false): Also list archived configs.
- How many (`limit`, number): The most score configs to list, 1 to 100. Defaults to 50. From 1 to 100.

**Outputs**

- `count` (number): How many were listed
- `score_configs` (list): The score configs

**Example output**

```json
{
  "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 (`name`, text): Only scores with this name; several separated by commas.
- Trace ID (`trace_id`, text): Only scores of this trace.
- Observation ID (`observation_id`, text): Only scores of this observation (give its trace too).
- Session ID (`session_id`, text): Only ones in this session (conversation).
- Source (`source`, text): Only scores from here: the API, people annotating, or evaluators. One of: `API`, `ANNOTATION`, `EVAL` (Evaluation).
- Type (`data_type`, text): Only scores of this kind. One of: `NUMERIC` (Number), `BOOLEAN` (True or false), `CATEGORICAL` (Category), `TEXT`.
- At least (`min_value`, number): Only number scores of this value or more.
- At most (`max_value`, number): Only number scores of this value or less, such as 0.5 for low scores.
- Since (`since`, date and time): Only scores from this time on. Defaults to 7 days ago.
- Until (`until`, date and time): Only ones before this time. Defaults to now.
- How many (`limit`, number): The most scores to list, 1 to 100. Defaults to 25. From 1 to 100.

**Outputs**

- `average` (number): The average of the number and true/false values listed
- `count` (number): How many were listed
- `scores` (list): The scores, the latest first
- `since` (text): The start of the time looked at (ISO 8601)
- `until` (text): The end of the time looked at (ISO 8601)

**Example output**

```json
{
  "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 (`name`, text): Only traces with this name, such as support-chat.
- User (`user`, text): Only ones for this user, as your app names them (Langfuse's User ID).
- Session ID (`session_id`, text): Only ones in this session (conversation).
- Tags (`tags`, list): Only traces with all of these tags.
- Environment (`environment`, text): Only traces from this environment, such as production.
- Since (`since`, date and time): Only traces from this time on. Defaults to 7 days ago.
- Until (`until`, date and time): Only ones before this time. Defaults to now.
- How many (`limit`, number): The most traces to list, 1 to 100. Defaults to 25. From 1 to 100.

**Outputs**

- `count` (number): How many traces were listed
- `since` (text): The start of the time looked at (ISO 8601)
- `traces` (list): The traces, the latest first
- `until` (text): The end of the time looked at (ISO 8601)

**Example output**

```json
{
  "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 (`name`, text, required): What the trace is, such as support-chat or nightly-summary.
- Input (`input`, text): What went in, such as the user's question or {"messages": [...]}. JSON is kept as JSON.
- Output (`output`, text): What came out, such as the model's answer. JSON is kept as JSON.
- User (`user`, text): The user it was for, as your app names them.
- Session ID (`session_id`, text): The session (conversation) it is part of, to group traces.
- Tags (`tags`, list): Tags to find it by.
- Metadata (`metadata`, object): More about it, such as {"customer": "acme"}.
- Environment (`environment`, text): Its environment, such as production or staging: lowercase letters, numbers and dashes.
- Release (`release`, text): Your app's release, such as 2026.11.3.
- Version (`version`, text): The version of what ran, such as v2.
- Type (`observation_type`, text): What it records. Defaults to Generation when a model is given, otherwise Span. One of: `span`, `generation`, `event`, `agent`, `tool`, `retriever`.
- Model (`model`, text): 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_tokens`, number): For a generation: tokens sent to the model. At least 0.
- Output tokens (`output_tokens`, number): For a generation: tokens the model wrote. At least 0.
- Cost (USD) (`cost`, number): 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_name`, text): The Langfuse prompt it used, to link the two.
- Prompt version (`prompt_version`, number): That prompt's version, such as the version of Get prompt. At least 1.
- Level (`level`, text): How it went: Error or Warning marks it in Langfuse. Defaults to Default. One of: `DEBUG`, `DEFAULT`, `WARNING`, `ERROR`. Default: `DEFAULT`.
- Status message (`status_message`, text): What to say about how it went, such as the error.
- Start time (`start_time`, date and time): When it started. Defaults to now.
- End time (`end_time`, date and time): When it ended. Defaults to the start time.

**Outputs**

- `link` (text): A link to the trace in Langfuse
- `name` (text): The trace's name
- `observation_id` (text): The ID of the observation logged
- `observation_type` (text): What was logged: SPAN, GENERATION, EVENT and so on
- `session_id` (text): The session it is part of
- `tags` (list): Its tags
- `trace_id` (text): The trace's ID
- `user_id` (text): The user it was for

**Example output**

```json
{
  "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"
}
```
