---
title: Blob storage export field reference
description: Field names and types for enriched observations, scores, and deprecated legacy blob storage exports.
sidebarTitle: Export Field Reference
---

# Blob storage export field reference [#blob-storage-export-field-reference]

Use this reference when building a consumer for the [blob storage export](/docs/api-and-data-platform/features/export-to-blob-storage). Types match JSON and JSONL output. Timestamps use `YYYY-MM-DD HH:MM:SS.ffffff` in UTC.

## Exported files [#export-sources]

| File               | When it is exported      |
| ------------------ | ------------------------ |
| `observations_v2/` | Current enriched export  |
| `scores/`          | Every export             |
| `traces/`          | Deprecated legacy export |
| `observations/`    | Deprecated legacy export |

For configuration and migration steps, see [Export to blob storage](/docs/api-and-data-platform/features/export-to-blob-storage).

## Enriched observations (`observations_v2/`) [#enriched-observations]

Each row represents one observation and includes its trace context. Only the [selected field groups](/docs/api-and-data-platform/features/export-to-blob-storage#export-field-groups) appear; `core` is always included.

| Field                     | Type                       | Description                                                                                                                       |
| ------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `id`                      | string                     | Unique observation identifier.                                                                                                    |
| `trace_id`                | string                     | Trace identifier shared by related observations and scores.                                                                       |
| `project_id`              | string                     | Langfuse project identifier.                                                                                                      |
| `environment`             | string                     | Environment label.                                                                                                                |
| `type`                    | string                     | Observation type: `SPAN`, `GENERATION`, `EVENT`, `AGENT`, `TOOL`, `CHAIN`, `RETRIEVER`, `EVALUATOR`, `EMBEDDING`, or `GUARDRAIL`. |
| `parent_observation_id`   | string                     | Parent observation identifier; empty for a root observation.                                                                      |
| `is_root_observation`     | boolean                    | Whether the observation is a logical root.                                                                                        |
| `start_time`              | string (timestamp)         | When the observation started.                                                                                                     |
| `end_time`                | string (timestamp) or null | When the observation ended.                                                                                                       |
| `name`                    | string                     | User-defined observation name.                                                                                                    |
| `metadata`                | object                     | User-supplied observation metadata.                                                                                               |
| `level`                   | string                     | `DEBUG`, `DEFAULT`, `WARNING`, or `ERROR`.                                                                                        |
| `status_message`          | string                     | Status or error message.                                                                                                          |
| `version`                 | string                     | User-defined version.                                                                                                             |
| `input`                   | string                     | Observation input; may contain plain text or JSON.                                                                                |
| `output`                  | string                     | Observation output; may contain plain text or JSON.                                                                               |
| `provided_model_name`     | string                     | Model name supplied by the SDK or user.                                                                                           |
| `model_parameters`        | string                     | Model parameters encoded as JSON.                                                                                                 |
| `usage_details`           | object (string → integer)  | Token usage by category, such as `input`, `output`, and `total`.                                                                  |
| `cost_details`            | object (string → number)   | Cost in USD by category.                                                                                                          |
| `completion_start_time`   | string (timestamp) or null | When the first streamed token was generated.                                                                                      |
| `prompt_name`             | string                     | Langfuse prompt name.                                                                                                             |
| `prompt_version`          | integer or null            | Langfuse prompt version.                                                                                                          |
| `total_cost`              | number                     | Total observation cost in USD; `0` when no cost was recorded.                                                                     |
| `latency`                 | number or null             | Duration in seconds.                                                                                                              |
| `time_to_first_token`     | number or null             | Time to first token in seconds.                                                                                                   |
| `model_id`                | string                     | Matched Langfuse model definition identifier.                                                                                     |
| `created_at`              | string (timestamp)         | Row creation time.                                                                                                                |
| `updated_at`              | string (timestamp)         | Last row update time.                                                                                                             |
| `prompt_id`               | string                     | Langfuse prompt identifier.                                                                                                       |
| `tool_calls`              | array of strings           | Tool calls encoded as JSON strings.                                                                                               |
| `tool_call_names`         | array of strings           | Names of called tools.                                                                                                            |
| `tool_definitions`        | object                     | Tool or function schemas supplied to the model.                                                                                   |
| `usage_pricing_tier_id`   | string or null             | Pricing tier identifier used for cost calculation.                                                                                |
| `usage_pricing_tier_name` | string or null             | Pricing tier name used for cost calculation.                                                                                      |
| `input_price`             | string or null             | Matched per-unit input price; omitted from Parquet.                                                                               |
| `output_price`            | string or null             | Matched per-unit output price; omitted from Parquet.                                                                              |
| `total_price`             | string or null             | Matched flat per-call price; omitted from Parquet.                                                                                |
| `user_id`                 | string                     | End-user identifier from the trace.                                                                                               |
| `session_id`              | string                     | Session identifier from the trace.                                                                                                |
| `trace_name`              | string                     | Trace name.                                                                                                                       |
| `tags`                    | array of strings           | Trace tags.                                                                                                                       |
| `release`                 | string                     | Trace release.                                                                                                                    |
| `bookmarked`              | boolean                    | Whether the trace is bookmarked.                                                                                                  |
| `public`                  | boolean                    | Whether the trace is public.                                                                                                      |

  Integrations created on or after 2026-04-01 export `latency` and
  `time_to_first_token` in seconds. Older integrations export these fields in
  milliseconds for backward compatibility.

## Scores (`scores/`) [#scores]

Scores are always exported. Their fields are not configurable. Scores with data type `NUMERIC`, `BOOLEAN`, `CATEGORICAL`, or `TEXT` are included; [corrections](/docs/observability/features/corrections) (data type `CORRECTION`) are not.

| Field            | Type               | Description                                            |
| ---------------- | ------------------ | ------------------------------------------------------ |
| `id`             | string             | Unique score identifier.                               |
| `timestamp`      | string (timestamp) | Score creation time.                                   |
| `project_id`     | string             | Langfuse project identifier.                           |
| `environment`    | string             | Environment label.                                     |
| `trace_id`       | string or null     | Associated trace identifier.                           |
| `observation_id` | string or null     | Associated observation identifier.                     |
| `session_id`     | string or null     | Associated session identifier.                         |
| `dataset_run_id` | string or null     | Associated dataset run identifier.                     |
| `name`           | string             | Score name.                                            |
| `value`          | number             | Numeric value; `TEXT` scores use `0`.                  |
| `source`         | string             | `API`, `ANNOTATION`, or `EVAL`.                        |
| `comment`        | string or null     | Optional comment or evaluator reasoning.               |
| `data_type`      | string             | `NUMERIC`, `BOOLEAN`, `CATEGORICAL`, or `TEXT`.        |
| `string_value`   | string or null     | Category label or text value; null for numeric scores. |
| `created_at`     | string (timestamp) | Row creation time.                                     |
| `updated_at`     | string (timestamp) | Last row update time.                                  |

## Legacy exports [#legacy-export-paths]

Legacy exports are deprecated. They split trace context into `traces/` and observation data into `observations/`; consumers join them on `trace_id`. See [upgrade a legacy export](/docs/api-and-data-platform/features/export-to-blob-storage#legacy-export-sources) before changing a consumer.

### Traces (`traces/`) [#traces]

The trace file has a fixed schema; field groups do not apply.

| Field         | Type               | Description                      |
| ------------- | ------------------ | -------------------------------- |
| `id`          | string             | Unique trace identifier.         |
| `timestamp`   | string (timestamp) | Trace creation time.             |
| `name`        | string             | User-defined trace name.         |
| `environment` | string             | Environment label.               |
| `project_id`  | string             | Langfuse project identifier.     |
| `metadata`    | object             | Trace metadata.                  |
| `user_id`     | string or null     | End-user identifier.             |
| `session_id`  | string or null     | Session identifier.              |
| `release`     | string or null     | Application release.             |
| `version`     | string or null     | User-defined version.            |
| `public`      | boolean            | Whether the trace is public.     |
| `bookmarked`  | boolean            | Whether the trace is bookmarked. |
| `tags`        | array of strings   | Trace tags.                      |
| `input`       | string or null     | Trace input.                     |
| `output`      | string or null     | Trace output.                    |
| `created_at`  | string (timestamp) | Row creation time.               |
| `updated_at`  | string (timestamp) | Last row update time.            |

Legacy trace-level `input`, `output`, `metadata`, `timestamp`, and `version` do not have direct equivalents in `observations_v2/`. Observation fields with the same names contain observation-level data instead.

<span id="traces-derived-fields" />

The trace file does not include `total_cost`, `latency`, `observations`, `scores`, or `html_path`.

### Observations (`observations/`) [#observations]

<span id="enriched-vs-legacy-differences" />

Each row represents one observation without its trace context; join `trace_id` to the `traces/` file to add it. Only the [selected field groups](/docs/api-and-data-platform/features/export-to-blob-storage#export-field-groups) appear; `core` is always included.

| Field                     | Type                       | Description                                                                                                                       |
| ------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `id`                      | string                     | Unique observation identifier.                                                                                                    |
| `trace_id`                | string                     | Trace identifier shared by related observations and scores.                                                                       |
| `project_id`              | string                     | Langfuse project identifier.                                                                                                      |
| `environment`             | string                     | Environment label.                                                                                                                |
| `type`                    | string                     | Observation type: `SPAN`, `GENERATION`, `EVENT`, `AGENT`, `TOOL`, `CHAIN`, `RETRIEVER`, `EVALUATOR`, `EMBEDDING`, or `GUARDRAIL`. |
| `parent_observation_id`   | string or null             | Parent observation identifier; null for a root observation.                                                                       |
| `start_time`              | string (timestamp)         | When the observation started.                                                                                                     |
| `end_time`                | string (timestamp) or null | When the observation ended.                                                                                                       |
| `name`                    | string                     | User-defined observation name.                                                                                                    |
| `metadata`                | object                     | User-supplied observation metadata.                                                                                               |
| `level`                   | string                     | `DEBUG`, `DEFAULT`, `WARNING`, or `ERROR`.                                                                                        |
| `status_message`          | string or null             | Status or error message.                                                                                                          |
| `version`                 | string or null             | User-defined version.                                                                                                             |
| `input`                   | string or null             | Observation input; may contain plain text or JSON.                                                                                |
| `output`                  | string or null             | Observation output; may contain plain text or JSON.                                                                               |
| `provided_model_name`     | string or null             | Model name supplied by the SDK or user.                                                                                           |
| `model_parameters`        | string or null             | Model parameters encoded as JSON.                                                                                                 |
| `usage_details`           | object (string → integer)  | Token usage by category, such as `input`, `output`, and `total`.                                                                  |
| `cost_details`            | object (string → number)   | Cost in USD by category.                                                                                                          |
| `completion_start_time`   | string (timestamp) or null | When the first streamed token was generated.                                                                                      |
| `prompt_name`             | string or null             | Langfuse prompt name.                                                                                                             |
| `prompt_version`          | integer or null            | Langfuse prompt version.                                                                                                          |
| `total_cost`              | number or null             | Total observation cost in USD.                                                                                                    |
| `latency`                 | number or null             | Duration in seconds.                                                                                                              |
| `time_to_first_token`     | number or null             | Time to first token in seconds.                                                                                                   |
| `model_id`                | string or null             | Matched Langfuse model definition identifier.                                                                                     |
| `created_at`              | string (timestamp)         | Row creation time.                                                                                                                |
| `updated_at`              | string (timestamp)         | Last row update time.                                                                                                             |
| `prompt_id`               | string or null             | Langfuse prompt identifier.                                                                                                       |
| `tool_calls`              | array of strings           | Tool calls encoded as JSON strings.                                                                                               |
| `tool_call_names`         | array of strings           | Names of called tools.                                                                                                            |
| `tool_definitions`        | object                     | Tool or function schemas supplied to the model.                                                                                   |
| `usage_pricing_tier_name` | string or null             | Pricing tier name used for cost calculation.                                                                                      |
| `input_price`             | string or null             | Matched per-unit input price; omitted from Parquet.                                                                               |
| `output_price`            | string or null             | Matched per-unit output price; omitted from Parquet.                                                                              |
| `total_price`             | string or null             | Matched flat per-call price; omitted from Parquet.                                                                                |

Where a field appears in both observation files it carries the same meaning. Unset values are encoded differently, though: a field that is `null` above maps to one of three values in `observations_v2/` JSON and JSONL output.

| Value in `observations_v2/` | Fields                                                                                                                                                           |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `""` (empty string)         | `input`, `model_id`, `model_parameters`, `output`, `parent_observation_id`, `prompt_id`, `prompt_name`, `provided_model_name`, `status_message`, `version`       |
| `null`                      | `completion_start_time`, `end_time`, `input_price`, `latency`, `output_price`, `prompt_version`, `time_to_first_token`, `total_price`, `usage_pricing_tier_name` |
| `0`                         | `total_cost`                                                                                                                                                     |

Empty strings appear where the v4 events table stores the column as non-nullable. `total_cost` reads from `cost_details['total']`, so a `0` there cannot be told apart from a genuine zero cost.

For the field groups that select these columns and how they differ from the enriched export, see [what changes in the exported data](/docs/api-and-data-platform/features/export-to-blob-storage#legacy-field-differences).

## Parquet differences [#parquet-exports]

Parquet uses internal encoding and compression, so gzip does not apply.

Observation files omit `input_price`, `output_price`, and `total_price`. Use `cost_details` and `total_cost` for cost data.

Trace and score fields are the same across all formats.

## File organization [#file-organization]

See [process exports](/docs/api-and-data-platform/features/export-to-blob-storage#consume-exports) for paths, filenames, and the manifest workflow.

<!-- 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/api-and-data-platform/features/blob-storage-export-fields.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>.