---
title: Experiments API
sidebarTitle: Experiments API
description: Retrieve experiment runs, items, outputs, and evaluation scores from Langfuse.
---

# Experiments API

**Where is this feature available?**

| Plan | Availability |
| --- | --- |
| Hobby | Available |
| Core | Available |
| Pro | Available |
| Enterprise | Available |
| Self Hosted | Langfuse v4+ |

The Experiments API lets you retrieve experiment data from Langfuse for
analysis, evaluation pipelines, notebooks, and CI/CD workflows. An experiment
is a run of your application against test data. Each experiment item represents
one input, its expected output, and the actual output produced by your
application.

For the complete request and response contract, see the
[Experiments API reference](https://api.reference.langfuse.com/#tag/experiments).

## Choose the right API

| If you want to...                                                                           | Use                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Run experiments and ingest experiment data                                                  | [Experiment runner SDK](/docs/evaluation/experiments/experiments-via-sdk) or [Experiments via OpenTelemetry](/docs/evaluation/experiments/experiments-via-opentelemetry) |
| List experiment runs and their summaries                                                    | `GET /api/public/experiments?fromStartTime=2026-01-01T00:00:00Z`                                                                                                         |
| Retrieve experiment items and their inputs, outputs, expected outputs, metadata, and scores | `GET /api/public/experiment-items?fromStartTime=2026-01-01T00:00:00Z`                                                                                                    |
| Retrieve the complete trace and observation tree for an item                                | [Observations API v2](/docs/api-and-data-platform/features/observations-api#v2), using the item's `traceId`                                                              |
| Query evaluation scores independently                                                       | [Scores API v3](/docs/api-and-data-platform/features/scores-api#v3)                                                                                                      |

The experiment endpoints support filtering, cursor-based pagination, and
optional response fields. Refer to the [Experiments API reference](https://api.reference.langfuse.com/#tag/experiments)
for the available filters and response fields.

## Experiment-level and item-level scores

Experiment-level scores summarize the complete run. Item-level and trace-level
scores evaluate individual experiment items. The Experiments API returns both
levels in their corresponding responses, while the [Scores API v3](/docs/api-and-data-platform/features/scores-api#v3)
is useful when scores are the primary data you want to query.

## Related resources

- [Experiments via SDK](/docs/evaluation/experiments/experiments-via-sdk) — run experiments with the Python or JS/TS SDK.
- [Experiments via OpenTelemetry](/docs/evaluation/experiments/experiments-via-opentelemetry) — ingest experiment spans from OpenTelemetry, then follow the [attribute guide](/integrations/native/opentelemetry/experiments).
- [Experiments data model](/docs/evaluation/experiments/data-model) — understand how datasets, experiments, items, traces, observations, and scores relate.
- [Observations API v2](/docs/api-and-data-platform/features/observations-api#v2) — retrieve row-level trace and observation data.
- [Scores API v3](/docs/api-and-data-platform/features/scores-api#v3) — retrieve evaluation and annotation scores.

<!-- 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/experiments-api.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>.