openapi: 3.0.1
info:
title: langfuse AnnotationQueues Trace 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: Trace
paths:
/api/public/traces/{traceId}:
get:
description: Get a specific trace
operationId: trace_get
tags:
- Trace
parameters:
- name: traceId
in: path
description: The unique langfuse identifier of a trace
required: true
schema:
type: string
- name: fields
in: query
description: 'Comma-separated list of fields to include in the response. Available field groups: ''core'' (always included), ''io'' (input, output, metadata), ''scores'', ''observations'', ''metrics''. If not specified, all fields are returned. Example: ''core,scores,metrics''. Note: Excluded ''observations'' or ''scores'' fields return empty arrays; excluded ''metrics'' returns -1 for ''totalCost'' and ''latency''.'
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/TraceWithFullDetails'
'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 specific trace
operationId: trace_delete
tags:
- Trace
parameters:
- name: traceId
in: path
description: The unique langfuse identifier of the trace to delete
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteTraceResponse'
'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/traces:
get:
description: Get list of traces
operationId: trace_list
tags:
- Trace
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. If you encounter api issues due to too large page sizes, try to reduce the limit.
required: false
schema:
type: integer
nullable: true
- name: userId
in: query
required: false
schema:
type: string
nullable: true
- name: name
in: query
required: false
schema:
type: string
nullable: true
- name: sessionId
in: query
required: false
schema:
type: string
nullable: true
- name: fromTimestamp
in: query
description: Optional filter to only include traces with a trace.timestamp on or after a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: toTimestamp
in: query
description: Optional filter to only include traces with a trace.timestamp before a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: orderBy
in: query
description: 'Format of the string [field].[asc/desc]. Fields: id, timestamp, name, userId, release, version, public, bookmarked, sessionId. Example: timestamp.asc'
required: false
schema:
type: string
nullable: true
- name: tags
in: query
description: Only traces that include all of these tags will be returned.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: version
in: query
description: Optional filter to only include traces with a certain version.
required: false
schema:
type: string
nullable: true
- name: release
in: query
description: Optional filter to only include traces with a certain release.
required: false
schema:
type: string
nullable: true
- name: environment
in: query
description: Optional filter for traces where the environment is one of the provided values.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: fields
in: query
description: 'Comma-separated list of fields to include in the response. Available field groups: ''core'' (always included), ''io'' (input, output, metadata), ''scores'', ''observations'', ''metrics''. If not specified, all fields are returned. Example: ''core,scores,metrics''. Note: Excluded ''observations'' or ''scores'' fields return empty arrays; excluded ''metrics'' returns -1 for ''totalCost'' and ''latency''.'
required: false
schema:
type: string
nullable: true
- name: filter
in: query
description: "JSON string containing an array of filter conditions. When provided, this takes precedence over query parameter filters (userId, name, sessionId, tags, version, release, environment, fromTimestamp, toTimestamp).\n\n## Filter Structure\nEach filter condition has the following structure:\n```json\n[\n {\n \"type\": string, // Required. One of: \"datetime\", \"string\", \"number\", \"stringOptions\", \"categoryOptions\", \"arrayOptions\", \"stringObject\", \"numberObject\", \"boolean\", \"null\"\n \"column\": string, // Required. Column to filter on (see available columns below)\n \"operator\": string, // Required. Operator based on type:\n // - datetime: \">\", \"<\", \">=\", \"<=\"\n // - string: \"=\", \"contains\", \"does not contain\", \"starts with\", \"ends with\"\n // - stringOptions: \"any of\", \"none of\"\n // - categoryOptions: \"any of\", \"none of\"\n // - arrayOptions: \"any of\", \"none of\", \"all of\"\n // - number: \"=\", \">\", \"<\", \">=\", \"<=\"\n // - stringObject: \"=\", \"contains\", \"does not contain\", \"starts with\", \"ends with\"\n // - numberObject: \"=\", \">\", \"<\", \">=\", \"<=\"\n // - boolean: \"=\", \"<>\"\n // - null: \"is null\", \"is not null\"\n \"value\": any, // Required (except for null type). Value to compare against. Type depends on filter type\n \"key\": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata\n }\n]\n```\n\n## Available Columns\n\n### Core Trace Fields\n- `id` (string) - Trace ID\n- `name` (string) - Trace name\n- `timestamp` (datetime) - Trace timestamp\n- `userId` (string) - User ID\n- `sessionId` (string) - Session ID\n- `environment` (string) - Environment tag\n- `version` (string) - Version tag\n- `release` (string) - Release tag\n- `tags` (arrayOptions) - Array of tags\n- `bookmarked` (boolean) - Bookmark status\n\n### Structured Data\n- `metadata` (stringObject/numberObject/categoryOptions) - Metadata key-value pairs. Use `key` parameter to filter on specific metadata keys.\n\n### Aggregated Metrics (from observations)\nThese metrics are aggregated from all observations within the trace:\n- `latency` (number) - Latency in seconds (time from first observation start to last observation end)\n- `inputTokens` (number) - Total input tokens across all observations\n- `outputTokens` (number) - Total output tokens across all observations\n- `totalTokens` (number) - Total tokens (alias: `tokens`)\n- `inputCost` (number) - Total input cost in USD\n- `outputCost` (number) - Total output cost in USD\n- `totalCost` (number) - Total cost in USD\n\n### Observation Level Aggregations\nThese fields aggregate observation levels within the trace:\n- `level` (string) - Highest severity level (ERROR > WARNING > DEFAULT > DEBUG)\n- `warningCount` (number) - Count of WARNING level observations\n- `errorCount` (number) - Count of ERROR level observations\n- `defaultCount` (number) - Count of DEFAULT level observations\n- `debugCount` (number) - Count of DEBUG level observations\n\n### Scores (requires join with scores table)\n- `scores_avg` (number) - Average of numeric scores (alias: `scores`)\n- `score_categories` (categoryOptions) - Categorical score values\n\n## Filter Examples\n```json\n[\n {\n \"type\": \"datetime\",\n \"column\": \"timestamp\",\n \"operator\": \">=\",\n \"value\": \"2024-01-01T00:00:00Z\"\n },\n {\n \"type\": \"string\",\n \"column\": \"userId\",\n \"operator\": \"=\",\n \"value\": \"user-123\"\n },\n {\n \"type\": \"number\",\n \"column\": \"totalCost\",\n \"operator\": \">=\",\n \"value\": 0.01\n },\n {\n \"type\": \"arrayOptions\",\n \"column\": \"tags\",\n \"operator\": \"all of\",\n \"value\": [\"production\", \"critical\"]\n },\n {\n \"type\": \"stringObject\",\n \"column\": \"metadata\",\n \"key\": \"customer_tier\",\n \"operator\": \"=\",\n \"value\": \"enterprise\"\n }\n]\n```\n\n## Performance Notes\n- Filtering on `userId`, `sessionId`, or `metadata` may enable skip indexes for better query performance\n- Score filters require a join with the scores table and may impact query performance"
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Traces'
'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 multiple traces
operationId: trace_deleteMultiple
tags:
- Trace
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteTraceResponse'
'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:
type: object
properties:
traceIds:
type: array
items:
type: string
description: List of trace IDs to delete
required:
- traceIds
components:
schemas:
BooleanScoreV1:
title: BooleanScoreV1
type: object
properties:
value:
type: number
format: double
description: The numeric value of the score. Equals 1 for "True" and 0 for "False"
stringValue:
type: string
description: The string representation of the score value. Is inferred from the numeric value and equals "True" or "False"
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
TraceWithDetails:
title: TraceWithDetails
type: object
properties:
htmlPath:
type: string
description: Path of trace in Langfuse UI
latency:
type: number
format: double
nullable: true
description: Latency of trace in seconds
totalCost:
type: number
format: double
nullable: true
description: Cost of trace in USD
observations:
type: array
items:
type: string
nullable: true
description: List of observation ids
scores:
type: array
items:
type: string
nullable: true
description: List of score ids
required:
- htmlPath
allOf:
- $ref: '#/components/schemas/Trace'
NumericScoreV1:
title: NumericScoreV1
type: object
properties:
value:
type: number
format: double
description: The numeric value of the score
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
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
Observation:
title: Observation
type: object
properties:
id:
type: string
description: The unique identifier of the observation
traceId:
type: string
nullable: true
description: The trace ID associated with the observation
type:
type: string
description: The type of the observation
name:
type: string
nullable: true
description: The name of the observation
startTime:
type: string
format: date-time
description: The start time of the observation
endTime:
type: string
format: date-time
nullable: true
description: The end time of the observation.
completionStartTime:
type: string
format: date-time
nullable: true
description: The completion start time of the observation
model:
type: string
nullable: true
description: The model used for the observation
modelParameters:
description: The parameters of the model used for the observation
input:
description: The input data of the observation
version:
type: string
nullable: true
description: The version of the observation
metadata:
description: Additional metadata of the observation
output:
description: The output data of the observation
usage:
$ref: '#/components/schemas/Usage'
description: (Deprecated. Use usageDetails and costDetails instead.) The usage data of the observation
level:
$ref: '#/components/schemas/ObservationLevel'
description: The level of the observation
statusMessage:
type: string
nullable: true
description: The status message of the observation
parentObservationId:
type: string
nullable: true
description: The parent observation ID
promptId:
type: string
nullable: true
description: The prompt ID associated with the observation
usageDetails:
type: object
additionalProperties:
type: integer
description: 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: object
additionalProperties:
type: number
format: double
description: 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
description: The environment from which this observation originated. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'.
required:
- id
- type
- startTime
- modelParameters
- input
- metadata
- output
- usage
- level
- usageDetails
- costDetails
- environment
BaseScoreV1:
title: BaseScoreV1
type: object
properties:
id:
type: string
traceId:
type: string
name:
type: string
source:
$ref: '#/components/schemas/ScoreSource'
observationId:
type: string
nullable: true
description: The observation ID associated with the score
timestamp:
type: string
format: date-time
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
authorUserId:
type: string
nullable: true
description: The user ID of the author
comment:
type: string
nullable: true
description: Comment on the score
metadata:
description: Metadata associated with the score
configId:
type: string
nullable: true
description: 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: string
nullable: true
description: The annotation queue referenced by the score. Indicates if score was initially created while processing annotation queue.
environment:
type: string
description: The environment from which this score originated. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'.
required:
- id
- traceId
- name
- source
- timestamp
- createdAt
- updatedAt
- metadata
- environment
TraceWithFullDetails:
title: TraceWithFullDetails
type: object
properties:
htmlPath:
type: string
description: Path of trace in Langfuse UI
latency:
type: number
format: double
nullable: true
description: Latency of trace in seconds
totalCost:
type: number
format: double
nullable: true
description: Cost of trace in USD
observations:
type: array
items:
$ref: '#/components/schemas/ObservationsView'
description: List of observations
scores:
type: array
items:
$ref: '#/components/schemas/ScoreV1'
description: List of scores
required:
- htmlPath
- observations
- scores
allOf:
- $ref: '#/components/schemas/Trace'
Traces:
title: Traces
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TraceWithDetails'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CategoricalScoreV1:
title: CategoricalScoreV1
type: object
properties:
value:
type: number
format: double
description: Represents the numeric category mapping of the stringValue. If no config is linked, defaults to 0.
stringValue:
type: string
description: The string representation of the score value. If no config is linked, can be any string. Otherwise, must map to a config category
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
Trace:
title: Trace
type: object
properties:
id:
type: string
description: The unique identifier of a trace
timestamp:
type: string
format: date-time
description: The timestamp when the trace was created
name:
type: string
nullable: true
description: The name of the trace
input:
nullable: true
description: The input data of the trace. Can be any JSON.
output:
nullable: true
description: The output data of the trace. Can be any JSON.
sessionId:
type: string
nullable: true
description: The session identifier associated with the trace
release:
type: string
nullable: true
description: The release version of the application when the trace was created
version:
type: string
nullable: true
description: The version of the trace
userId:
type: string
nullable: true
description: The user identifier associated with the trace
metadata:
nullable: true
description: The metadata associated with the trace. Can be any JSON.
tags:
type: array
items:
type: string
description: The tags associated with the trace.
public:
type: boolean
description: Public traces are accessible via url without login
environment:
type: string
description: The environment from which this trace originated. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'.
required:
- id
- timestamp
- tags
- public
- environment
Usage:
title: Usage
type: object
description: (Deprecated. Use usageDetails and costDetails instead.) Standard interface for usage and cost
properties:
input:
type: integer
description: Number of input units (e.g. tokens)
output:
type: integer
description: Number of output units (e.g. tokens)
total:
type: integer
description: Defaults to input+output if not set
unit:
type: string
nullable: true
description: Unit of measurement
inputCost:
type: number
format: double
nullable: true
description: USD input cost
outputCost:
type: number
format: double
nullable: true
description: USD output cost
totalCost:
type: number
format: double
nullable: true
description: USD total cost, defaults to input+output
required:
- input
- output
- total
ObservationLevel:
title: ObservationLevel
type: string
enum:
- DEBUG
- DEFAULT
- WARNING
- ERROR
ScoreSource:
title: ScoreSource
type: string
enum:
- ANNOTATION
- API
- EVAL
DeleteTraceResponse:
title: DeleteTraceResponse
type: object
properties:
message:
type: string
required:
- message
ScoreV1:
title: ScoreV1
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/NumericScoreV1'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/CategoricalScoreV1'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/BooleanScoreV1'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- TEXT
- $ref: '#/components/schemas/TextScoreV1'
required:
- dataType
TextScoreV1:
title: TextScoreV1
type: object
properties:
stringValue:
type: string
description: The text content of the score (1-500 characters)
required:
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
ObservationsView:
title: ObservationsView
type: object
properties:
promptName:
type: string
nullable: true
description: The name of the prompt associated with the observation
promptVersion:
type: integer
nullable: true
description: The version of the prompt associated with the observation
modelId:
type: string
nullable: true
description: The unique identifier of the model
inputPrice:
type: number
format: double
nullable: true
description: The price of the input in USD
outputPrice:
type: number
format: double
nullable: true
description: The price of the output in USD.
totalPrice:
type: number
format: double
nullable: true
description: The total price in USD.
calculatedInputCost:
type: number
format: double
nullable: true
description: (Deprecated. Use usageDetails and costDetails instead.) The calculated cost of the input in USD
calculatedOutputCost:
type: number
format: double
nullable: true
description: (Deprecated. Use usageDetails and costDetails instead.) The calculated cost of the output in USD
calculatedTotalCost:
type: number
format: double
nullable: true
description: (Deprecated. Use usageDetails and costDetails instead.) The calculated total cost in USD
latency:
type: number
format: double
nullable: true
description: The latency in seconds.
timeToFirstToken:
type: number
format: double
nullable: true
description: The time to the first token in seconds
allOf:
- $ref: '#/components/schemas/Observation'
securitySchemes:
BasicAuth:
type: http
scheme: basic