---
title: Public API
sidebarTitle: Public API
description: All Langfuse data and features are available via the API. Follow this guide to get started.
---

# Public API [#public-api]

Langfuse is open and meant to be extended via custom workflows and integrations. All Langfuse data and features are available via the API.

There are 3 different groups of APIs:

- This page -> Project-level APIs: CRUD traces/evals/prompts/configuration within a project
- [Organization-level APIs](/docs/administration/scim-and-org-api): provision projects, users (SCIM), and permissions
- [Instance Management API](/self-hosting/administration/instance-management-api): administer organizations on self-hosted installations

## API reference [#api-reference]

References:

- API Reference: https://api.reference.langfuse.com
- OpenAPI spec: https://cloud.langfuse.com/generated/api/openapi.yml

## Quickstart [#quickstart]

<Steps>

### Obtain credentials [#authentication]

The public and secret keys are available in the Langfuse project settings.

### Select the regional base URL [#base-urls]

<Tabs items={["Path", "Cloud US", "Cloud EU", "Cloud Japan", "HIPAA US"]}>

<Tab>

```
/api/public
```

</Tab>
<Tab>

```
https://us.cloud.langfuse.com/api/public
```

</Tab>
<Tab>

```
https://cloud.langfuse.com/api/public
```

</Tab>
<Tab>

```
https://jp.cloud.langfuse.com/api/public
```

</Tab>
<Tab>

```
https://hipaa.cloud.langfuse.com/api/public
```

</Tab>
</Tabs>

### Make an authenticated request

Example:

```bash
curl -u public-key:secret-key https://cloud.langfuse.com/api/public/projects
```

### Understand the result

A successful response returns the project associated with your API key:

```json
{
  "data": [
    {
      "id": "clxxxx",
      "name": "My Project",
      "organization": {
        "id": "clyyyy",
        "name": "My Org"
      }
    }
  ]
}
```

Use the same credentials and regional base URL for the rest of the Public API.

</Steps>

## Access via SDKs [#access-via-sdks]

Both the Langfuse [Python SDK](/docs/observability/sdk/overview) and the [JS/TS SDK](/docs/observability/sdk/overview) provide a strongly-typed wrapper around our public REST API for your convenience. The API methods are accessible via the `api` property on the Langfuse client instance in both SDKs.

You can use your editor's Intellisense to explore the API methods and their parameters.

In Python SDK v4 and JS/TS SDK v5, the high-performance observations and
metrics resources are the defaults: `api.observations` and `api.metrics`.
Scores API v3 is available as `api.scores_v3` in Python SDK `4.8.1+` and
`api.scoresV3` in JS/TS SDK `5.5.0+`; the `api.scores` v2 reads are deprecated
([migration guide](/faq/all/deprecated-api-migration#scores)). Deprecated v1
resources moved under `api.legacy.*` (Python: `*_v1`, JS/TS: `*V1`). See
[Query via SDKs](/docs/api-and-data-platform/features/query-via-sdk) for SDK examples.

Observations API v2 and Metrics API v2 are available on Langfuse Cloud and
self-hosted Langfuse v4. On self-hosted Langfuse v3, use the `api.legacy.*`
resources. See [Versions & Compatibility](/docs/compatibility#sdk-server).

When fetching [prompts](/docs/prompts/get-started#use-prompt), please use the `get_prompt` (Python) / `getPrompt` (JS/TS) methods on the Langfuse client to benefit from client-side caching, automatic retries, and fallbacks.

<LangTabs items={["Python SDK", "JS/TS SDK", "Java SDK"]}>
<Tab>

When using the [Python SDK](/docs/observability/sdk/overview):

```python
from langfuse import get_client

langfuse = get_client()

# Retrieve row-level observations via Observations API v2
observations = langfuse.api.observations.get_many(
    trace_id="trace-id",
    fields="core,basic,usage",
    limit=100,
)

# Retrieve aggregates via Metrics API v2
metrics = langfuse.api.metrics.metrics(query="""
{
  "view": "observations",
  "metrics": [{"measure": "totalCost", "aggregation": "sum"}],
  "dimensions": [{"field": "providedModelName"}],
  "filters": [],
  "fromTimestamp": "2025-05-01T00:00:00Z",
  "toTimestamp": "2025-05-13T00:00:00Z"
}
""")

# explore more endpoints via Intellisense
langfuse.api.*
await langfuse.async_api.*
```

</Tab>

<Tab>

```ts
import { LangfuseClient } from '@langfuse/client';

const langfuse = new LangfuseClient();

// Retrieve row-level observations via Observations API v2
const observations = await langfuse.api.observations.getMany({
  traceId: "trace-id",
  fields: "core,basic,usage",
  limit: 100,
});

// Retrieve aggregates via Metrics API v2
const metrics = await langfuse.api.metrics.metrics({
  query: JSON.stringify({
    view: "observations",
    metrics: [{ measure: "totalCost", aggregation: "sum" }],
    dimensions: [{ field: "providedModelName" }],
    filters: [],
    fromTimestamp: "2025-05-01T00:00:00Z",
    toTimestamp: "2025-05-13T00:00:00Z"
  })
});

// explore more endpoints via Intellisense
langfuse.api.*
```

</Tab>

<Tab>

Install Langfuse by adding the following to your `pom.xml`:

```xml
<dependencies>
  <dependency>
    <groupId>com.langfuse</groupId>
    <artifactId>langfuse-java</artifactId>
    <version>0.0.1-SNAPSHOT</version>
  </dependency>
</dependencies>

<repositories>
  <repository>
    <id>github</id>
    <name>GitHub Package Registry</name>
    <url>https://maven.pkg.github.com/langfuse/langfuse-java</url>
  </repository>
</repositories>
```

Instantiate and use the Java SDK via:

```java
import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.prompts.types.PromptMetaListResponse;
import com.langfuse.client.core.LangfuseClientApiException;

LangfuseClient client = LangfuseClient.builder()
  .url("https://cloud.langfuse.com") // 🇪🇺 EU data region
  // Other Langfuse data regions:
  // .url("https://us.cloud.langfuse.com") // 🇺🇸 US
  // .url("https://jp.cloud.langfuse.com") // 🇯🇵 Japan
  // .url("https://hipaa.cloud.langfuse.com") // ⚕️ HIPAA
  // .url("http://localhost:3000") // 🏠 Local deployment
  .credentials("pk-lf-...", "sk-lf-...")
  .build();

try {
  PromptMetaListResponse prompts = client.prompts().list();
} catch (LangfuseClientApiException error) {
  System.out.println(error.getBody());
  System.out.println(error.getStatusCode());
}
```

</Tab>
</LangTabs>

## Ingest Traces via the API

  The OpenTelemetry endpoint is the supported path for trace ingestion. The
  legacy Ingestion API is deprecated and is sunset on Langfuse Cloud on November 16, 2026 (2026-11-16); on self-hosted v4 it is unavailable once you run
  the default `events_only` write mode. Switch to the OpenTelemetry endpoint
  now. Follow the [custom ingestion migration
  guide](/integrations/native/opentelemetry/migration-to-v4) to map legacy
  events to v4-ready OTEL spans. This deprecation applies to trace and
  observation events. Current SDK score helpers send `score-create` events to
  the same endpoint; those events remain supported after the cutover.

- [OpenTelemetry Traces Ingestion Endpoint](https://api.reference.langfuse.com/#tag/opentelemetry/POST/api/public/otel/v1/traces) implements the OTLP/HTTP specification for trace ingestion, providing native OpenTelemetry integration for Langfuse Observability.
- (Sunset as of Nov 16, 2026) [Ingestion API](https://api.reference.langfuse.com/#tag/ingestion/POST/api/public/ingestion) allows trace ingestion using an API.

## Retrieve Data via the API

For new data extraction workflows, use the high-performance data APIs:

- [Observations API v2](/docs/api-and-data-platform/features/observations-api#v2) - Retrieve observation data (spans, generations, events) from Langfuse for custom workflows, evaluation pipelines, and analytics.
- [Scores API v3](/docs/api-and-data-platform/features/scores-api#v3) - Retrieve score data (evaluations, annotations, and API-ingested scores) with a typed value field and cursor-based pagination.
- [Metrics API v2](/docs/metrics/features/metrics-api#v2) - Retrieve aggregated analytics and metrics from your Langfuse data.

The deprecated trace, observation, score, and metrics read APIs are documented, with migration steps, in [Migration of deprecated APIs](/faq/all/deprecated-api-migration).

## Alternatives

You can also export data via:

- [UI](/docs/api-and-data-platform/features/export-from-ui) - Manual batch-exports from the Langfuse UI
- [Blob Storage](/docs/api-and-data-platform/features/export-to-blob-storage) - Scheduled automated exports to cloud storage

## FAQ

## Related API resources [#related-api-resources]

- [Query via SDKs](/docs/api-and-data-platform/features/query-via-sdk) — typed Python and JS/TS wrappers for the same endpoints
- [Observations API v2](/docs/api-and-data-platform/features/observations-api#v2) — retrieve row-level spans, generations, and events
- [Scores API v3](/docs/api-and-data-platform/features/scores-api#v3) — retrieve evaluation and annotation scores
- [Metrics API v2](/docs/metrics/features/metrics-api#v2) — retrieve aggregated analytics
- [Experiments API](/docs/api-and-data-platform/features/experiments-api) — retrieve experiment runs and items
- [CLI](/docs/api-and-data-platform/features/cli) — call the Public API from the terminal
- [MCP Server](/docs/api-and-data-platform/features/mcp-server) — connect AI assistants to Langfuse data
- [Organization-level APIs](/docs/administration/scim-and-org-api) — provision projects, users (SCIM), and permissions
- [Instance Management API](/self-hosting/administration/instance-management-api) — administer organizations on self-hosted installations
- [Migration of deprecated APIs](/faq/all/deprecated-api-migration) — replacements for sunset read and ingestion endpoints

## GitHub Discussions

<!-- 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/public-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>.