Implementation:Langfuse Langfuse PromptService GetPrompt

Knowledge Sources	Langfuse
Domains	Prompt Management, Caching, API Design
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete tool for retrieving prompts by name and version or label, with Redis caching and dependency resolution, provided by Langfuse.

Description

The getPrompt method on the PromptService class is the primary read-path entry point. It accepts a PromptParams object specifying a project ID, prompt name, and either a version number or a label string. The method orchestrates a multi-tier retrieval:

1. Lock check: Calls shouldUseCache to determine if caching is available. This checks both the cacheEnabled flag and whether a lock key exists in Redis. If a lock is active (indicating an in-flight mutation), the cache is bypassed.
2. Cache read: If caching is available, calls getCachedPrompt which uses GETEX to read the cached value and simultaneously refresh its TTL. Records a cache hit or miss metric.
3. Database fallback: If the cache is unavailable, locked, or misses, calls getDbPrompt which queries PostgreSQL using Prisma. For version lookups, it matches on (projectId, name, version). For label lookups, it uses Prisma's has array filter on the labels field.
4. Resolution: The raw database prompt is passed through resolvePrompt, which calls buildAndResolvePromptGraph to recursively inline all dependency references. The resolved content replaces the original prompt field.
5. isActive computation: The isActive field is computed from whether the prompt's labels array includes "production". This replaces a deprecated stored boolean.
6. Cache back-fill: If caching is available and not locked, the resolved result is written to Redis with the configured TTL and registered in the key index set.

The method returns a PromptResult, which extends the Prisma Prompt type with a resolutionGraph field (null if no dependencies) and the computed isActive field.

Usage

Use getPrompt from SDK-facing API handlers, the prompt playground, experiment runners, or any server-side code that needs to fetch a prompt for LLM invocation. The method is safe to call concurrently and handles all caching, locking, and resolution transparently.

Code Reference

Source Location

• Repository: langfuse
• File: packages/shared/src/server/services/PromptService/index.ts
• Lines: 44-127

Signature

public async getPrompt(params: PromptParams): Promise<PromptResult | null>

Where PromptParams is defined as:

type PromptParams = {
  projectId: string;
  promptName: string;
} & (
  | { version: number; label: undefined }
  | { version: null | undefined; label: string }
);

And PromptResult is:

type PromptResult = Prompt & {
  resolutionGraph: PromptGraph | null;
};

type PromptGraph = {
  root: PromptReference;
  dependencies: Record<string, PromptReference[]>;
};

type PromptReference = Pick<Prompt, "id" | "version" | "name">;

Import

import { PromptService } from "@langfuse/shared/src/server";

I/O Contract

Inputs

Name	Type	Required	Description
projectId	string	Yes	The project ID scoping the prompt lookup.
promptName	string	Yes	The name of the prompt to retrieve.
version	number	Conditional	The specific version number to retrieve. Required if label is not provided.
label	string	Conditional	The label to resolve (e.g., "production", "latest"). Required if version is not provided. The system returns the prompt version that carries this label.

Outputs

Name	Type	Description
PromptResult | null	PromptResult | null	The resolved prompt or null if no matching prompt exists. PromptResult includes all Prompt fields (id, projectId, name, version, prompt, type, labels, tags, config, createdBy, commitMessage, createdAt, updatedAt, isActive) plus resolutionGraph.
prompt (field)	string | any[]	The resolved prompt content. If the prompt had dependency tags, they have been replaced with the inlined content of the referenced prompts.
resolutionGraph (field)	PromptGraph | null	The dependency graph as an adjacency list. Null if the prompt has no dependencies. Contains a root reference and a dependencies map from parent IDs to arrays of child references.
isActive (field)	boolean	True if the prompt's labels array includes "production". This is a computed property, not a stored value.

Usage Examples

Retrieve by Label

import { PromptService } from "@langfuse/shared/src/server";

const promptService = new PromptService(prisma, redis);

const result = await promptService.getPrompt({
  projectId: "proj_abc123",
  promptName: "summarization-system",
  label: "production",
  version: undefined,
});

if (result) {
  console.log(result.version);          // e.g., 5
  console.log(result.prompt);           // Fully resolved content
  console.log(result.isActive);         // true (has "production" label)
  console.log(result.resolutionGraph);  // null or PromptGraph
}

Retrieve by Version

const result = await promptService.getPrompt({
  projectId: "proj_abc123",
  promptName: "summarization-system",
  version: 3,
  label: undefined,
});

if (result) {
  console.log(result.version);  // 3 (exact version requested)
  console.log(result.isActive); // depends on whether version 3 has "production" label
}

Handle Missing Prompts

const result = await promptService.getPrompt({
  projectId: "proj_abc123",
  promptName: "nonexistent-prompt",
  label: "production",
  version: undefined,
});

// result === null (no matching prompt found)

Retrieve a Prompt with Dependencies

// Assume "main-prompt" version 1 contains:
//   "Instructions: @@@langfusePrompt:name=shared-rules|version=2@@@ Now answer."
// And "shared-rules" version 2 contains:
//   "Be concise and factual."

const result = await promptService.getPrompt({
  projectId: "proj_abc123",
  promptName: "main-prompt",
  version: 1,
  label: undefined,
});

console.log(result.prompt);
// "Instructions: Be concise and factual. Now answer."

console.log(result.resolutionGraph);
// {
//   root: { id: "prompt_001", name: "main-prompt", version: 1 },
//   dependencies: {
//     "prompt_001": [{ id: "prompt_xyz", name: "shared-rules", version: 2 }]
//   }
// }

Related Pages

Implements Principle

• Principle:Langfuse_Langfuse_Prompt_Retrieval_and_Resolution