Langfuse icon

Langfuse

Log LLM traces, spans, generations, and scores to Langfuse, or query traces, prompts, datasets, sessions, and more via the Public API.

Actions28

Ingestion → Generation Create

AI-generated

Summary

Create a new generation observation in Langfuse ingestion API to record details about a generation event, including timing, model info, usage, cost, and metadata.

Inputs

  • name (required) — Human-readable name for the generation observation.
  • model — Model name used in the generation event.
  • inputJson — JSON string representing the input payload for the generation.
  • outputJson — JSON string representing the output payload from the generation.
  • traceId — Trace ID this generation attaches to; auto-filled from previous step if blank to link to existing trace.
  • eventId — Optional event ID to ensure idempotency and deduplication.
  • observationId — Leave blank to auto-generate an observation ID for creation.
  • parentObservationId — Optional parent observation ID for nested observations.
  • timestamp — ISO 8601 timestamp for the event; if blank, current time is used.
  • startTime — ISO 8601 start time for the generation.
  • modelParametersJson — JSON string with model parameters used for the generation.
  • promptName — Prompt name linked to the generation.
  • promptVersion — Optional prompt version linked to the generation.
  • promptLabelsJson — JSON array of prompt labels stored as metadata prompt_labels.
  • promptTokens — Input token count for the generation; leave blank if unknown.
  • completionTokens — Output token count for the generation; leave blank if unknown.
  • totalTokens — Total token count for the generation; leave blank if unknown.
  • usageDetailsJson — JSON object with detailed usage breakdown, overriding token count fields if provided.
  • costDetailsJson — JSON object with detailed cost breakdown by input, output, and total.
  • completionStartTime — Optional completion start time for the generation.
  • level — Optional observation log level.
  • statusMessage — Optional status message attached to the observation.
  • environment — Optional environment label (e.g., production) for the generation.
  • metadataJson — Additional JSON metadata stored with the generation.
  • failOnBatchErrors — Whether to fail the item on partial ingestion errors returned by Langfuse.

Output shape

a JSON object representing the ingestion API response for the created generation observation including any auto-generated IDs

The operation auto-fills and returns traceId and observationId if not explicitly provided, allowing chained operations to link to the same trace. Partial ingestion errors can be surfaced when failOnBatchErrors is enabled.

Examples

Example 1: Create a generation observation linked to a previous trace with model details and usage tokens.

Provide traceId (or leave blank to auto-link), a name, model name, JSON input/output strings, and optional token counts to record a detailed generation event.

Links

Discussion