---
title: Data Model
description: Data model for Score and ScoreConfig objects in Langfuse.
sidebarTitle: Data Model
---

# Scores Data Model

This page describes the data model for score-related objects in Langfuse. For an overview of what scores are and when to use them, see the [Scores overview](/docs/evaluation/scores/overview). For datasets, experiment runs, and function definitions, see the [Experiments data model](/docs/evaluation/experiments/data-model).

For detailed reference please refer to

- the [Python SDK reference](https://python.reference.langfuse.com)
- the [JS/TS SDK reference](https://js.reference.langfuse.com)
- the [API reference](https://api.reference.langfuse.com)

## Scores [#scores]

Scores are the data object to store evaluation results. They are used to assign evaluation scores to traces, observations, sessions, or dataset runs. Scores can be added manually via annotations, programmatically via the SDK/API, or automatically via LLM-as-a-Judge evaluators.

<br />

```mermaid
classDiagram
direction LR
    class Score {
        id
        name
        value
        stringValue
        dataType
        source
        comment
        configId
    }

    Score --> Trace: traceId
    Score --> Observation: observationId
    Score --> Session: sessionId
    Score --> DatasetRun: datasetRunId
```

Scores have the following properties:

- Each Score references **exactly one** of `Trace`, `Observation`, `Session`, or `DatasetRun`
- Scores are either **numeric**, **categorical**, **boolean**, or **text** (see [Score Types](/docs/evaluation/scores/overview#score-types))
- Scores can **optionally be linked to a `ScoreConfig`** to ensure they comply with a specific schema

### Score object [#score-object]

| Attribute       | Type   | Required | Description                                                                                                                                                                                    |
| --------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | string | Yes      | Unique identifier of the score. Auto-generated by SDKs. Optionally can also be used as an idempotency key to update scores.                                                                    |
| `name`          | string | Yes      | Name of the score, e.g. user_feedback, hallucination_eval                                                                                                                                      |
| `value`         | number | No       | Numeric value of the score. Always defined for numeric and boolean scores. Optional for categorical scores. Not used for text scores.                                                          |
| `stringValue`   | string | No       | String value of the score. Used for categorical, boolean (string equivalent), and text data types. Automatically set for categorical scores based on the config if the `configId` is provided. |
| `dataType`      | string | No       | Automatically set based on the config data type when the `configId` is provided. Otherwise can be defined manually as `NUMERIC`, `CATEGORICAL`, `BOOLEAN`, or `TEXT`                           |
| `source`        | string | Yes      | Automatically set based on the source of the score. Can be either `API`, `EVAL`, or `ANNOTATION`                                                                                               |
| `comment`       | string | No       | Evaluation comment, commonly used for user feedback, eval reasoning output or internal notes                                                                                                   |
| `traceId`       | string | No       | Id of the trace the score relates to                                                                                                                                                           |
| `observationId` | string | No       | Id of the observation (e.g. LLM call) the score relates to                                                                                                                                     |
| `sessionId`     | string | No       | Id of the session the score relates to                                                                                                                                                         |
| `datasetRunId`  | string | No       | Id of the dataset run the score relates to                                                                                                                                                     |
| `configId`      | string | No       | Score config id to ensure that the score follows a specific schema. Can be defined in the Langfuse UI or via API.                                                                              |

### Common Use Cases [#common-use-cases]

| Level       | Description                                                                |
| ----------- | -------------------------------------------------------------------------- |
| Trace       | Used for evaluation of a single interaction. (most common)                 |
| Observation | Used for evaluation of a single observation below the trace level.         |
| Session     | Used for comprehensive evaluation of outputs across multiple interactions. |
| Dataset Run | Used for performance scores of a Dataset Run.                              |

## Score Config [#score-config]

Score configs are used to ensure that your scores follow a specific schema. Using score configs allows you to standardize your scoring schema across your team and ensure that scores are consistent and comparable for future analysis.

You can define a `ScoreConfig` in the Langfuse UI or via our API. Configs are immutable but can be archived (and restored anytime).

```mermaid
classDiagram
  Score --> ScoreConfig: configId
```

A score config includes:

- **Score name**
- **Data type:** `NUMERIC`, `CATEGORICAL`, `BOOLEAN`, `TEXT`
- **Constraints on score value range** (Min/Max for numerical, Custom categories for categorical data types, 1-500 characters for text)

### ScoreConfig object [#scoreconfig-object]

| Attribute     | Type    | Required | Description                                                                           |
| ------------- | ------- | -------- | ------------------------------------------------------------------------------------- |
| `id`          | string  | Yes      | Unique identifier of the score config.                                                |
| `name`        | string  | Yes      | Name of the score config, e.g. user_feedback, hallucination_eval                      |
| `dataType`    | string  | Yes      | Can be either `NUMERIC`, `CATEGORICAL`, `BOOLEAN`, or `TEXT`                          |
| `isArchived`  | boolean | No       | Whether the score config is archived. Defaults to false                               |
| `minValue`    | number  | No       | Sets minimum value for numerical scores. If not set, the minimum value defaults to -∞ |
| `maxValue`    | number  | No       | Sets maximum value for numerical scores. If not set, the maximum value defaults to +∞ |
| `categories`  | list    | No       | Defines categories for categorical scores. List of objects with label value pairs     |
| `description` | string  | No       | Provides further description of the score configuration                               |

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/docs/evaluation/scores/data-model.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.