Public API

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

/api/public

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

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

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

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

References:

API Reference: https://api.reference.langfuse.com
OpenAPI spec: https://cloud.langfuse.com/generated/api/openapi.yml
Postman collection: https://cloud.langfuse.com/generated/postman/collection.json

There are 3 different groups of APIs:

This page -> Project-level APIs: CRUD traces/evals/prompts/configuration within a project
Organization-level APIs: provision projects, users (SCIM), and permissions
Instance Management API: administer organizations on self-hosted installations

Authentication

Authenticate with the API using Basic Auth. The API keys are available in the Neural Inverse project settings.

Username: Neural Inverse Public Key
Password: Neural Inverse Secret Key

Example:

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

Both the Neural Inverse Python SDK and the JS/TS SDK provide a strongly-typed wrapper around our public REST API for your convenience. The API methods are accessible via the api property on the Neural Inverse 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 resources are the defaults: api.observations, api.scores, and api.metrics. Legacy v1 resources moved under api.legacy.* (Python: *_v1, JS/TS: *V1). See Query via SDKs for SDK examples.

Observations API v2 and Metrics API v2 are currently Cloud-only. For self-hosted deployments, use the endpoints available in your Neural Inverse version.

When fetching prompts, please use the get_prompt (Python) / getPrompt (JS/TS) methods on the Neural Inverse client to benefit from client-side caching, automatic retries, and fallbacks.

When using the Python SDK:

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.get(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.*

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.get({
  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.*

Install Neural Inverse by adding the following to your pom.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:

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 Neural Inverse 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());
}

Ingest Traces via the API

The OpenTelemetry Endpoint will replace the Ingestion API in the future. Therefore, it is strongly recommended to switch to the OpenTelemetry Endpoint for trace ingestion. Please refer to the OpenTelemetry docs for more information.

OpenTelemetry Traces Ingestion Endpoint implements the OTLP/HTTP specification for trace ingestion, providing native OpenTelemetry integration for Neural Inverse Observability.
(Legacy) Ingestion API allows trace ingestion using an API.

Retrieve Data via the API

For new data extraction workflows, use the v2 data APIs:

Observations API v2 - Retrieve observation data (spans, generations, events) from Neural Inverse for custom workflows, evaluation pipelines, and analytics.
Metrics API v2 - Retrieve aggregated analytics and metrics from your Neural Inverse data.

Older trace, observation, and metrics read APIs remain available, but are not recommended as the default for new extraction workflows because they are less performant at scale. See Observations API v2 for row-level data and Metrics API v2 for aggregates.

Alternatives

You can also export data via:

UI - Manual batch-exports from the Neural Inverse UI
Blob Storage - Scheduled automated exports to cloud storage

FAQ

GitHub Discussions

Was this page helpful?