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 → Finalize Span

AI-generated

Summary

Finalize an existing span by closing it with optional timing, metadata, and generation details to complete the observation in Langfuse.

Inputs

  • observationId — The ID of the span to finalize. If left blank, it auto-fills from the previous step's observationId output; set explicitly if the span was created earlier in the workflow.
  • endTime — ISO 8601 end time to close the span. If not provided, the current time is used.
  • startTime — Optional ISO 8601 start time. If omitted, the original span start time is preserved.
  • traceId — Trace ID to associate with the observation. Auto-filled from previous step's traceId if left blank.
  • name — Optional human-readable name for the span.
  • inputJson — Optional JSON input payload associated with the span.
  • outputJson — Optional JSON output payload associated with the span.
  • metadataJson — Additional JSON metadata to store with the span.
  • environment — Optional environment label, e.g., 'production'.
  • version — Optional version string for the observation.
  • level — Optional level string, e.g., 'info'.
  • statusMessage — Optional status message attached to the observation.
  • generationObservationId — Optional custom observation ID for a generated LLM call included when finalizing the span.
  • model — Model name used for the generation event tied to this span.
  • modelParametersJson — JSON object with model parameters.
  • promptName — Name of the prompt linked to the generation.
  • promptVersion — Optional version string for the prompt.
  • promptLabelsJson — JSON array of prompt labels stored in generation metadata.
  • 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 usage details overriding token counts, keyed by input, output, and total.
  • costDetailsJson — JSON cost details keyed by input, output, and total.
  • completionStartTime — Optional ISO 8601 start time for completion of the generation event.
  • eventId — Optional event ID for idempotency and deduplication.
  • timestamp — Optional ISO 8601 timestamp for the event; if blank, current time is used.

Output shape

a single observation finalization record including the finalized span and optionally associated generation event data.

The operation sends a batch of events to Langfuse to close the span and optionally finalize a generation event within the same trace. Blank ID fields auto-fill from the previous step's outputs to enable seamless chaining. Timing defaults to now if omitted. Partial ingestion errors can be surfaced if configured, enabling workflow branching on success/failure.

Links

Discussion