openapi: 3.0.1
info:
title: langfuse AnnotationQueues Models API
version: ''
description: '## Authentication
Authenticate with the API using [Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication), get API keys in the project settings:
- username: Langfuse Public Key
- password: Langfuse Secret Key
## Exports
- OpenAPI spec: https://cloud.langfuse.com/generated/api/openapi.yml'
tags:
- name: Models
paths:
/api/public/models:
post:
description: Create a model
operationId: models_create
tags:
- Models
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateModelRequest'
get:
description: Get all models
operationId: models_list
tags:
- Models
parameters:
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedModels'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/models/{id}:
get:
description: Get a model
operationId: models_get
tags:
- Models
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: Delete a model. Cannot delete models managed by Langfuse. You can create your own definition with the same modelName to override the definition though.
operationId: models_delete
tags:
- Models
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
components:
schemas:
Model:
title: Model
type: object
description: '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:
type: string
modelName:
type: string
description: '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<observation.startTime'
matchPattern:
type: string
description: Regex pattern which matches this model definition to generation.model. Useful in case of fine-tuned models. If you want to exact match, use `(?i)^modelname$`
startDate:
type: string
format: date-time
nullable: true
description: Apply only to generations which are newer than this ISO date.
unit:
$ref: '#/components/schemas/ModelUsageUnit'
nullable: true
description: Unit used by this model.
inputPrice:
type: number
format: double
nullable: true
description: Deprecated. See 'prices' instead. Price (USD) per input unit
outputPrice:
type: number
format: double
nullable: true
description: Deprecated. See 'prices' instead. Price (USD) per output unit
totalPrice:
type: number
format: double
nullable: true
description: Deprecated. See 'prices' instead. Price (USD) per total unit. Cannot be set if input or output price is set.
tokenizerId:
type: string
nullable: true
description: Optional. Tokenizer to be applied to observations which match to this model. See docs for more details.
tokenizerConfig:
description: Optional. Configuration for the selected tokenizer. Needs to be JSON. See docs for more details.
isLangfuseManaged:
type: boolean
createdAt:
type: string
format: date-time
description: Timestamp when the model was created
prices:
type: object
additionalProperties:
$ref: '#/components/schemas/ModelPrice'
description: '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.'
pricingTiers:
type: array
items:
$ref: '#/components/schemas/PricingTier'
description: '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.'
required:
- id
- modelName
- matchPattern
- tokenizerConfig
- isLangfuseManaged
- createdAt
- prices
- pricingTiers
ModelPrice:
title: ModelPrice
type: object
properties:
price:
type: number
format: double
required:
- price
utilsMetaResponse:
title: utilsMetaResponse
type: object
properties:
page:
type: integer
description: current page number
limit:
type: integer
description: number of items per page
totalItems:
type: integer
description: number of total items given the current filters/selection (if any)
totalPages:
type: integer
description: number of total pages given the current limit
required:
- page
- limit
- totalItems
- totalPages
PaginatedModels:
title: PaginatedModels
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Model'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateModelRequest:
title: CreateModelRequest
type: object
properties:
modelName:
type: string
description: '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<observation.startTime'
matchPattern:
type: string
description: Regex pattern which matches this model definition to generation.model. Useful in case of fine-tuned models. If you want to exact match, use `(?i)^modelname$`
startDate:
type: string
format: date-time
nullable: true
description: Apply only to generations which are newer than this ISO date.
unit:
$ref: '#/components/schemas/ModelUsageUnit'
nullable: true
description: Unit used by this model.
inputPrice:
type: number
format: double
nullable: true
description: Deprecated. Use 'pricingTiers' instead. Price (USD) per input unit. Creates a default tier if pricingTiers not provided.
outputPrice:
type: number
format: double
nullable: true
description: Deprecated. Use 'pricingTiers' instead. Price (USD) per output unit. Creates a default tier if pricingTiers not provided.
totalPrice:
type: number
format: double
nullable: true
description: Deprecated. Use 'pricingTiers' instead. Price (USD) per total units. Cannot be set if input or output price is set. Creates a default tier if pricingTiers not provided.
pricingTiers:
type: array
items:
$ref: '#/components/schemas/PricingTierInput'
nullable: true
description: "Optional. Array of pricing tiers for this model.\n\nUse pricing tiers for all models - both those with threshold-based pricing variations and those with simple flat pricing:\n\n- For models with standard flat pricing: Create a single default tier with your prices\n (e.g., one tier with isDefault=true, priority=0, conditions=[], and your standard prices)\n\n- For models with threshold-based pricing: Create a default tier plus additional conditional tiers\n (e.g., default tier for standard usage + high-volume tier for usage above certain thresholds)\n\nRequirements:\n- Cannot be provided with flat prices (inputPrice/outputPrice/totalPrice) - use one approach or the other\n- Must include exactly one default tier with isDefault=true, priority=0, and conditions=[]\n- All tier names and priorities must be unique within the model\n- Each tier must define at least one price\n\nIf omitted, you must provide flat prices instead (inputPrice/outputPrice/totalPrice),\nwhich will automatically create a single default tier named \"Standard\"."
tokenizerId:
type: string
nullable: true
description: Optional. Tokenizer to be applied to observations which match to this model. See docs for more details.
tokenizerConfig:
nullable: true
description: Optional. Configuration for the selected tokenizer. Needs to be JSON. See docs for more details.
required:
- modelName
- matchPattern
PricingTierInput:
title: PricingTierInput
type: object
description: '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:
type: string
description: 'Name of the pricing tier for display and identification purposes.
Must be unique within the model. Common patterns: "Standard", "High Volume Tier", "Extended Context"'
isDefault:
type: boolean
description: '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.'
priority:
type: integer
description: '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.'
conditions:
type: array
items:
$ref: '#/components/schemas/PricingTierCondition'
description: '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.'
prices:
type: object
additionalProperties:
type: number
format: double
description: '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.'
required:
- name
- isDefault
- priority
- conditions
- prices
PricingTier:
title: PricingTier
type: object
description: '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:
type: string
description: Unique identifier for the pricing tier
name:
type: string
description: 'Name of the pricing tier for display and identification purposes.
Examples: "Standard", "High Volume Tier", "Large Context", "Extended Context Tier"'
isDefault:
type: boolean
description: '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.'
priority:
type: integer
description: '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.'
conditions:
type: array
items:
$ref: '#/components/schemas/PricingTierCondition'
description: '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").'
prices:
type: object
additionalProperties:
type: number
format: double
description: '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.'
required:
- id
- name
- isDefault
- priority
- conditions
- prices
PricingTierOperator:
title: PricingTierOperator
type: string
enum:
- gt
- gte
- lt
- lte
- eq
- neq
description: Comparison operators for pricing tier conditions
PricingTierCondition:
title: PricingTierCondition
type: object
description: '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:
type: string
description: '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.'
operator:
$ref: '#/components/schemas/PricingTierOperator'
description: '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)'
value:
type: number
format: double
description: Threshold value for comparison. For token-based pricing, this is typically the token count threshold (e.g., 200000 for a 200K token threshold).
caseSensitive:
type: boolean
description: Whether the regex pattern matching is case-sensitive. Default is false (case-insensitive matching).
required:
- usageDetailPattern
- operator
- value
- caseSensitive
ModelUsageUnit:
title: ModelUsageUnit
type: string
enum:
- CHARACTERS
- TOKENS
- MILLISECONDS
- SECONDS
- IMAGES
- REQUESTS
description: Unit of usage in Langfuse
securitySchemes:
BasicAuth:
type: http
scheme: basic