types: # Objects # Source: web/src/features/public-api/types/traces.ts - APITrace, APIExtendedTrace, GetTraceV1Response Trace: properties: id: type: string docs: The unique identifier of a trace timestamp: type: datetime docs: The timestamp when the trace was created name: type: nullable docs: The name of the trace input: type: optional docs: The input data of the trace. Can be any JSON. output: type: optional docs: The output data of the trace. Can be any JSON. sessionId: type: nullable docs: The session identifier associated with the trace release: type: nullable docs: The release version of the application when the trace was created version: type: nullable docs: The version of the trace userId: type: nullable docs: The user identifier associated with the trace metadata: type: optional docs: The metadata associated with the trace. Can be any JSON. tags: type: list docs: The tags associated with the trace. public: type: boolean docs: Public traces are accessible via url without login environment: type: string docs: The environment from which this trace originated. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'. TraceWithDetails: # GET /traces extends: Trace properties: htmlPath: type: string docs: Path of trace in Langfuse UI latency: type: optional> docs: Latency of trace in seconds totalCost: type: optional> docs: Cost of trace in USD observations: type: optional>> docs: List of observation ids scores: type: optional>> docs: List of score ids TraceWithFullDetails: # GET traces/[traceID] extends: Trace properties: htmlPath: type: string docs: Path of trace in Langfuse UI latency: type: optional> docs: Latency of trace in seconds totalCost: type: optional> docs: Cost of trace in USD observations: type: list docs: List of observations scores: type: list docs: List of scores # Source: web/src/features/public-api/types/sessions.ts - APISession Session: properties: id: string createdAt: datetime projectId: string environment: type: string docs: The environment from which this session originated. SessionWithTraces: extends: Session properties: traces: list # Source: web/src/features/public-api/types/observations.ts - APIObservation Observation: properties: id: type: string docs: The unique identifier of the observation traceId: type: nullable docs: The trace ID associated with the observation type: type: string docs: The type of the observation name: type: nullable docs: The name of the observation startTime: type: datetime docs: The start time of the observation endTime: type: nullable docs: The end time of the observation. completionStartTime: type: nullable docs: The completion start time of the observation model: type: nullable docs: The model used for the observation modelParameters: type: unknown docs: The parameters of the model used for the observation input: type: unknown docs: The input data of the observation version: type: nullable docs: The version of the observation metadata: type: unknown docs: Additional metadata of the observation output: type: unknown docs: The output data of the observation usage: type: Usage docs: (Deprecated. Use usageDetails and costDetails instead.) The usage data of the observation level: type: ObservationLevel docs: The level of the observation statusMessage: type: nullable docs: The status message of the observation parentObservationId: type: nullable docs: The parent observation ID promptId: type: nullable docs: The prompt ID associated with the observation usageDetails: type: map docs: The usage details of the observation. Key is the name of the usage metric, value is the number of units consumed. The total key is the sum of all (non-total) usage metrics or the total value ingested. costDetails: type: map docs: The cost details of the observation. Key is the name of the cost metric, value is the cost in USD. The total key is the sum of all (non-total) cost metrics or the total value ingested. environment: type: string docs: The environment from which this observation originated. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'. ObservationsView: extends: Observation properties: promptName: type: nullable docs: The name of the prompt associated with the observation promptVersion: type: nullable docs: The version of the prompt associated with the observation modelId: type: nullable docs: The unique identifier of the model inputPrice: type: nullable docs: The price of the input in USD outputPrice: type: nullable docs: The price of the output in USD. totalPrice: type: nullable docs: The total price in USD. calculatedInputCost: type: nullable docs: (Deprecated. Use usageDetails and costDetails instead.) The calculated cost of the input in USD calculatedOutputCost: type: nullable docs: (Deprecated. Use usageDetails and costDetails instead.) The calculated cost of the output in USD calculatedTotalCost: type: nullable docs: (Deprecated. Use usageDetails and costDetails instead.) The calculated total cost in USD latency: type: nullable docs: The latency in seconds. timeToFirstToken: type: nullable docs: The time to the first token in seconds Usage: docs: (Deprecated. Use usageDetails and costDetails instead.) Standard interface for usage and cost properties: input: docs: Number of input units (e.g. tokens) type: integer output: docs: Number of output units (e.g. tokens) type: integer total: docs: Defaults to input+output if not set type: integer unit: docs: Unit of measurement type: nullable inputCost: docs: USD input cost type: optional outputCost: docs: USD output cost type: optional totalCost: docs: USD total cost, defaults to input+output type: optional # Source: web/src/features/public-api/types/score-configs.ts - APIScoreConfig ScoreConfig: docs: Configuration for a score properties: id: string name: string createdAt: datetime updatedAt: datetime projectId: string dataType: ScoreConfigDataType isArchived: type: boolean docs: Whether the score config is archived. Defaults to false minValue: type: optional> docs: Sets minimum value for numerical scores. If not set, the minimum value defaults to -∞ maxValue: type: optional> docs: Sets maximum value for numerical scores. If not set, the maximum value defaults to +∞ categories: type: optional> docs: Configures custom categories for categorical scores description: type: optional> docs: Description of the score config ConfigCategory: properties: value: double label: string # Source: packages/shared/src/features/scores/interfaces/api/v1/schemas.ts - APIScoreSchemaV1 BaseScoreV1: properties: id: string traceId: string name: string source: ScoreSource observationId: type: optional> docs: The observation ID associated with the score timestamp: datetime createdAt: datetime updatedAt: datetime authorUserId: type: nullable docs: The user ID of the author comment: type: nullable docs: Comment on the score metadata: type: unknown docs: Metadata associated with the score configId: type: nullable docs: Reference a score config on a score. When set, config and score name must be equal and value must comply to optionally defined numerical range queueId: type: nullable docs: The annotation queue referenced by the score. Indicates if score was initially created while processing annotation queue. environment: type: string docs: The environment from which this score originated. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'. NumericScoreV1: extends: BaseScoreV1 properties: value: type: double docs: The numeric value of the score BooleanScoreV1: extends: BaseScoreV1 properties: value: type: double docs: The numeric value of the score. Equals 1 for "True" and 0 for "False" stringValue: type: string docs: The string representation of the score value. Is inferred from the numeric value and equals "True" or "False" CategoricalScoreV1: extends: BaseScoreV1 properties: value: type: double docs: Represents the numeric category mapping of the stringValue. If no config is linked, defaults to 0. stringValue: type: string docs: The string representation of the score value. If no config is linked, can be any string. Otherwise, must map to a config category ScoreV1: discriminant: "dataType" union: NUMERIC: type: NumericScoreV1 docs: "Score with NUMERIC data type" CATEGORICAL: type: CategoricalScoreV1 docs: "Score with CATEGORICAL data type" BOOLEAN: type: BooleanScoreV1 docs: "Score with BOOLEAN data type" # Source: packages/shared/src/features/scores/interfaces/api/v2/schemas.ts - APIScoreSchemaV2 BaseScore: properties: id: string traceId: type: optional> docs: The trace ID associated with the score sessionId: type: optional> docs: The session ID associated with the score observationId: type: optional> docs: The observation ID associated with the score datasetRunId: type: optional> docs: The dataset run ID associated with the score name: string source: ScoreSource timestamp: datetime createdAt: datetime updatedAt: datetime authorUserId: type: nullable docs: The user ID of the author comment: type: nullable docs: Comment on the score metadata: type: unknown docs: Metadata associated with the score configId: type: nullable docs: Reference a score config on a score. When set, config and score name must be equal and value must comply to optionally defined numerical range queueId: type: nullable docs: The annotation queue referenced by the score. Indicates if score was initially created while processing annotation queue. environment: type: string docs: The environment from which this score originated. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'. NumericScore: extends: BaseScore properties: value: type: double docs: The numeric value of the score BooleanScore: extends: BaseScore properties: value: type: double docs: The numeric value of the score. Equals 1 for "True" and 0 for "False" stringValue: type: string docs: The string representation of the score value. Is inferred from the numeric value and equals "True" or "False" CategoricalScore: extends: BaseScore properties: value: type: double docs: Represents the numeric category mapping of the stringValue. If no config is linked, defaults to 0. stringValue: type: string docs: The string representation of the score value. If no config is linked, can be any string. Otherwise, must map to a config category CorrectionScore: extends: BaseScore properties: value: type: double docs: The numeric value of the score. Always 0 for correction scores. stringValue: type: string docs: The string representation of the correction content Score: discriminant: "dataType" union: NUMERIC: type: NumericScore docs: "Score with NUMERIC data type" CATEGORICAL: type: CategoricalScore docs: "Score with CATEGORICAL data type" BOOLEAN: type: BooleanScore docs: "Score with BOOLEAN data type" CORRECTION: type: CorrectionScore docs: "Score with CORRECTION data type" CreateScoreValue: discriminated: false union: - double - string docs: The value of the score. Must be passed as string for categorical scores, and numeric for boolean and numeric scores # Source: web/src/features/public-api/types/comments.ts - APIComment Comment: properties: id: string projectId: string createdAt: datetime updatedAt: datetime objectType: CommentObjectType objectId: string content: string authorUserId: type: optional> docs: The user ID of the comment author # Source: web/src/features/public-api/types/datasets.ts - APIDataset Dataset: properties: id: string name: string description: type: nullable docs: Description of the dataset metadata: type: unknown docs: Metadata associated with the dataset inputSchema: type: nullable docs: JSON Schema for validating dataset item inputs expectedOutputSchema: type: nullable docs: JSON Schema for validating dataset item expected outputs projectId: string createdAt: datetime updatedAt: datetime # Source: web/src/features/public-api/types/datasets.ts - APIDatasetItem DatasetItem: properties: id: string status: DatasetStatus input: type: unknown docs: Input data for the dataset item expectedOutput: type: unknown docs: Expected output for the dataset item metadata: type: unknown docs: Metadata associated with the dataset item sourceTraceId: type: nullable docs: The trace ID that sourced this dataset item sourceObservationId: type: nullable docs: The observation ID that sourced this dataset item datasetId: string datasetName: string createdAt: datetime updatedAt: datetime # Source: web/src/features/public-api/types/datasets.ts - APIDatasetRunItem DatasetRunItem: properties: id: string datasetRunId: string datasetRunName: string datasetItemId: string traceId: string observationId: type: nullable docs: The observation ID associated with this run item createdAt: datetime updatedAt: datetime # Source: web/src/features/public-api/types/datasets.ts - APIDatasetRun DatasetRun: properties: id: type: string docs: Unique identifier of the dataset run name: type: string docs: Name of the dataset run description: type: nullable docs: Description of the run metadata: type: unknown docs: Metadata of the dataset run datasetId: type: string docs: Id of the associated dataset datasetName: type: string docs: Name of the associated dataset createdAt: type: datetime docs: The date and time when the dataset run was created updatedAt: type: datetime docs: The date and time when the dataset run was last updated DatasetRunWithItems: extends: DatasetRun properties: datasetRunItems: list # Source: web/src/features/public-api/types/models.ts - APIModelDefinition Model: docs: | Model definition used for transforming usage into USD cost and/or tokenization. Models can have either simple flat pricing or tiered pricing: - Flat pricing: Single price per usage type (legacy, but still supported) - Tiered pricing: Multiple pricing tiers with conditional matching based on usage patterns The pricing tiers approach is recommended for models with usage-based pricing variations. When using tiered pricing, the flat price fields (inputPrice, outputPrice, prices) are populated from the default tier for backward compatibility. properties: id: string modelName: docs: "Name of the model definition. If multiple with the same name exist, they are applied in the following order: (1) custom over built-in, (2) newest according to startTime where model.startTime unit: docs: Unit used by this model. type: optional> inputPrice: docs: Deprecated. See 'prices' instead. Price (USD) per input unit type: nullable outputPrice: docs: Deprecated. See 'prices' instead. Price (USD) per output unit type: nullable totalPrice: docs: Deprecated. See 'prices' instead. Price (USD) per total unit. Cannot be set if input or output price is set. type: nullable tokenizerId: docs: Optional. Tokenizer to be applied to observations which match to this model. See docs for more details. type: nullable tokenizerConfig: docs: Optional. Configuration for the selected tokenizer. Needs to be JSON. See docs for more details. type: unknown isLangfuseManaged: type: boolean createdAt: docs: Timestamp when the model was created type: datetime prices: docs: | Deprecated. Use 'pricingTiers' instead for models with usage-based pricing variations. This field shows prices by usage type from the default pricing tier. Maintained for backward compatibility. If the model uses tiered pricing, this field will be populated from the default tier's prices. type: map pricingTiers: docs: | Array of pricing tiers with conditional pricing based on usage thresholds. Pricing tiers enable accurate cost tracking for models that charge different rates based on usage patterns (e.g., different rates for high-volume usage, large context windows, or cached tokens). Each model must have exactly one default tier (isDefault=true, priority=0) that serves as a fallback. Additional conditional tiers can be defined with specific matching criteria. If this array is empty, the model uses legacy flat pricing from the inputPrice/outputPrice/totalPrice fields. type: list ModelPrice: properties: price: double PricingTierCondition: docs: | Condition for matching a pricing tier based on usage details. Used to implement tiered pricing models where costs vary based on usage thresholds. How it works: 1. The regex pattern matches against usage detail keys (e.g., "input_tokens", "input_cached") 2. Values of all matching keys are summed together 3. The sum is compared against the threshold value using the specified operator 4. All conditions in a tier must be met (AND logic) for the tier to match Common use cases: - Threshold-based pricing: Match when accumulated usage exceeds a certain amount - Usage-type-specific pricing: Different rates for cached vs non-cached tokens, or input vs output - Volume-based pricing: Different rates based on total request or token count properties: usageDetailPattern: docs: | Regex pattern to match against usage detail keys. All matching keys' values are summed for threshold comparison. Examples: - "^input" matches "input", "input_tokens", "input_cached", etc. - "^(input|prompt)" matches both "input_tokens" and "prompt_tokens" - "_cache$" matches "input_cache", "output_cache", etc. The pattern is case-insensitive by default. If no keys match, the sum is treated as zero. type: string operator: docs: | Comparison operator to apply between the summed value and the threshold. - gt: greater than (sum > threshold) - gte: greater than or equal (sum >= threshold) - lt: less than (sum < threshold) - lte: less than or equal (sum <= threshold) - eq: equal (sum == threshold) - neq: not equal (sum != threshold) type: PricingTierOperator value: docs: Threshold value for comparison. For token-based pricing, this is typically the token count threshold (e.g., 200000 for a 200K token threshold). type: double caseSensitive: docs: Whether the regex pattern matching is case-sensitive. Default is false (case-insensitive matching). type: boolean PricingTier: docs: | Pricing tier definition with conditional pricing based on usage thresholds. Pricing tiers enable accurate cost tracking for LLM providers that charge different rates based on usage patterns. For example, some providers charge higher rates when context size exceeds certain thresholds. How tier matching works: 1. Tiers are evaluated in ascending priority order (priority 1 before priority 2, etc.) 2. The first tier where ALL conditions match is selected 3. If no conditional tiers match, the default tier is used as a fallback 4. The default tier has priority 0 and no conditions Why priorities matter: - Lower priority numbers are evaluated first, allowing you to define specific cases before general ones - Example: Priority 1 for "high usage" (>200K tokens), Priority 2 for "medium usage" (>100K tokens), Priority 0 for default - Without proper ordering, a less specific condition might match before a more specific one Every model must have exactly one default tier to ensure cost calculation always succeeds. properties: id: docs: Unique identifier for the pricing tier type: string name: docs: | Name of the pricing tier for display and identification purposes. Examples: "Standard", "High Volume Tier", "Large Context", "Extended Context Tier" type: string isDefault: docs: | Whether this is the default tier. Every model must have exactly one default tier with priority 0 and no conditions. The default tier serves as a fallback when no conditional tiers match, ensuring cost calculation always succeeds. It typically represents the base pricing for standard usage patterns. type: boolean priority: docs: | Priority for tier matching evaluation. Lower numbers = higher priority (evaluated first). The default tier must always have priority 0. Conditional tiers should have priority 1, 2, 3, etc. Example ordering: - Priority 0: Default tier (no conditions, always matches as fallback) - Priority 1: High usage tier (e.g., >200K tokens) - Priority 2: Medium usage tier (e.g., >100K tokens) This ensures more specific conditions are checked before general ones. type: integer conditions: docs: | Array of conditions that must ALL be met for this tier to match (AND logic). The default tier must have an empty conditions array. Conditional tiers should have one or more conditions that define when this tier's pricing applies. Multiple conditions enable complex matching scenarios (e.g., "high input tokens AND low output tokens"). type: list prices: docs: | Prices (USD) by usage type for this tier. Common usage types: "input", "output", "total", "request", "image" Prices are specified in USD per unit (e.g., per token, per request, per second). Example: {"input": 0.000003, "output": 0.000015} means $3 per million input tokens and $15 per million output tokens. type: map PricingTierInput: docs: | Input schema for creating a pricing tier. The tier ID will be automatically generated server-side. When creating a model with pricing tiers: - Exactly one tier must have isDefault=true (the fallback tier) - The default tier must have priority=0 and conditions=[] - All tier names and priorities must be unique within the model - Each tier must define at least one price See PricingTier for detailed information about how tiers work and why they're useful. properties: name: docs: | Name of the pricing tier for display and identification purposes. Must be unique within the model. Common patterns: "Standard", "High Volume Tier", "Extended Context" type: string isDefault: docs: | Whether this is the default tier. Exactly one tier per model must be marked as default. Requirements for default tier: - Must have isDefault=true - Must have priority=0 - Must have empty conditions array (conditions=[]) The default tier acts as a fallback when no conditional tiers match. type: boolean priority: docs: | Priority for tier matching evaluation. Lower numbers = higher priority (evaluated first). Must be unique within the model. The default tier must have priority=0. Conditional tiers should use priority 1, 2, 3, etc. based on their specificity. type: integer conditions: docs: | Array of conditions that must ALL be met for this tier to match (AND logic). The default tier must have an empty array (conditions=[]). Conditional tiers should define one or more conditions that specify when this tier's pricing applies. Each condition specifies a regex pattern, operator, and threshold value for matching against usage details. type: list prices: docs: | Prices (USD) by usage type for this tier. At least one price must be defined. Common usage types: "input", "output", "total", "request", "image" Prices are in USD per unit (e.g., per token). Example: {"input": 0.000003, "output": 0.000015} represents $3 per million input tokens and $15 per million output tokens. type: map PricingTierOperator: docs: Comparison operators for pricing tier conditions enum: - gt - gte - lt - lte - eq - neq # Utilities ModelUsageUnit: docs: Unit of usage in Langfuse enum: - CHARACTERS - TOKENS - MILLISECONDS - SECONDS - IMAGES - REQUESTS ObservationLevel: enum: - DEBUG - DEFAULT - WARNING - ERROR MapValue: discriminated: false union: - optional - optional - optional - optional> CommentObjectType: enum: - TRACE - OBSERVATION - SESSION - PROMPT DatasetStatus: enum: - ACTIVE - ARCHIVED ScoreSource: enum: - ANNOTATION - API - EVAL ScoreConfigDataType: enum: - NUMERIC - BOOLEAN - CATEGORICAL ScoreDataType: enum: - NUMERIC - BOOLEAN - CATEGORICAL - CORRECTION errors: Error: status-code: 400 type: unknown UnauthorizedError: status-code: 401 type: unknown AccessDeniedError: status-code: 403 type: unknown NotFoundError: status-code: 404 type: unknown MethodNotAllowedError: status-code: 405 type: unknown