Langfuse Ingestion API

openapi: 3.2.0
info:
  title: langfuse AnnotationQueues Ingestion API
  version: '1.0'
  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'
servers:
- url: https://cloud.langfuse.com/api/public
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Ingestion
paths:
  /api/public/ingestion:
    post:
      description: '**Legacy endpoint for batch ingestion for Langfuse Observability.**


        -> Please use the OpenTelemetry endpoint (`/api/public/otel/v1/traces`). Learn more: https://langfuse.com/integrations/native/opentelemetry


        Within each batch, there can be multiple events.

        Each event has a type, an id, a timestamp, metadata and a body.

        Internally, we refer to this as the "event envelope" as it tells us something about the event but not the trace.

        We use the event id within this envelope to deduplicate messages to avoid processing the same event twice, i.e. the event id should be unique per request.

        The event.body.id is the ID of the actual trace and will be used for updates and will be visible within the Langfuse App.

        I.e. if you want to update a trace, you''d use the same body id, but separate event IDs.


        Notes:

        - Introduction to data model: https://langfuse.com/docs/observability/data-model

        - Batch sizes are limited to 3.5 MB in total. You need to adjust the number of events per batch accordingly.

        - The API does not return a 4xx status code for input errors. Instead, it responds with a 207 status code, which includes a list of the encountered errors.'
      operationId: ingestion_batch
      tags:
      - Ingestion
      parameters: []
      responses:
        '207':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestionResponse'
              examples:
                Example1:
                  value:
                    successes:
                    - id: abcdef-1234-5678-90ab
                      status: 201
                    errors: []
                Example2:
                  value:
                    successes:
                    - id: abcdef-1234-5678-90ab
                      status: 201
                    errors: []
                Example3:
                  value:
                    successes:
                    - id: abcdef-1234-5678-90ab
                      status: 201
                    errors: []
        '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:
                batch:
                  type: array
                  items:
                    $ref: '#/components/schemas/IngestionEvent'
                  description: Batch of tracing events to be ingested. Discriminated by attribute `type`.
                metadata:
                  description: Optional. Metadata field used by the Langfuse SDKs for debugging.
              required:
              - batch
            examples:
              Example1:
                value:
                  batch:
                  - id: abcdef-1234-5678-90ab
                    timestamp: '2022-01-01T00:00:00.000Z'
                    type: trace-create
                    body:
                      id: abcdef-1234-5678-90ab
                      timestamp: '2022-01-01T00:00:00.000Z'
                      environment: production
                      name: My Trace
                      userId: 1234-5678-90ab-cdef
                      input: My input
                      output: My output
                      sessionId: 1234-5678-90ab-cdef
                      release: 1.0.0
                      version: 1.0.0
                      metadata: My metadata
                      tags:
                      - tag1
                      - tag2
                      public: true
              Example2:
                value:
                  batch:
                  - id: abcdef-1234-5678-90ab
                    timestamp: '2022-01-01T00:00:00.000Z'
                    type: span-create
                    body:
                      id: abcdef-1234-5678-90ab
                      traceId: 1234-5678-90ab-cdef
                      startTime: '2022-01-01T00:00:00.000Z'
                      environment: test
              Example3:
                value:
                  batch:
                  - id: abcdef-1234-5678-90ab
                    timestamp: '2022-01-01T00:00:00.000Z'
                    type: score-create
                    body:
                      id: abcdef-1234-5678-90ab
                      traceId: 1234-5678-90ab-cdef
                      name: My Score
                      value: 0.9
                      environment: default
components:
  schemas:
    MapValue:
      title: MapValue
      oneOf:
      - type:
        - string
        - 'null'
      - type:
        - integer
        - 'null'
      - type:
        - integer
        - 'null'
        format: float
      - type:
        - boolean
        - 'null'
      - type:
        - array
        - 'null'
        items:
          type: string
    ScoreEvent:
      title: ScoreEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/ScoreBody'
      required:
      - body
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
    UpdateEventBody:
      title: UpdateEventBody
      type: object
      properties:
        id:
          type: string
      required:
      - id
      allOf:
      - $ref: '#/components/schemas/OptionalObservationBody'
    ObservationType:
      title: ObservationType
      type: string
      enum:
      - SPAN
      - GENERATION
      - EVENT
      - AGENT
      - TOOL
      - CHAIN
      - RETRIEVER
      - EVALUATOR
      - EMBEDDING
      - GUARDRAIL
    IngestionSuccess:
      title: IngestionSuccess
      type: object
      properties:
        id:
          type: string
        status:
          type: integer
      required:
      - id
      - status
    CreateGenerationBody:
      title: CreateGenerationBody
      type: object
      properties:
        completionStartTime:
          type:
          - string
          - 'null'
          format: date-time
        model:
          type:
          - string
          - 'null'
        modelParameters:
          type:
          - object
          - 'null'
          additionalProperties:
            $ref: '#/components/schemas/MapValue'
        usage:
          $ref: '#/components/schemas/IngestionUsage'
        usageDetails:
          $ref: '#/components/schemas/UsageDetails'
        costDetails:
          type:
          - object
          - 'null'
          additionalProperties:
            type: number
            format: double
        promptName:
          type:
          - string
          - 'null'
        promptVersion:
          type:
          - integer
          - 'null'
      allOf:
      - $ref: '#/components/schemas/CreateSpanBody'
    CreateScoreValue:
      title: CreateScoreValue
      oneOf:
      - type: number
        format: double
      - type: string
      description: The value of the score. Must be passed as string for categorical and text scores, and numeric for boolean and numeric scores
    UsageDetails:
      title: UsageDetails
      oneOf:
      - type: object
        additionalProperties:
          type: integer
      - $ref: '#/components/schemas/OpenAICompletionUsageSchema'
      - $ref: '#/components/schemas/OpenAIResponseUsageSchema'
    TraceBody:
      title: TraceBody
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        timestamp:
          type:
          - string
          - 'null'
          format: date-time
        name:
          type:
          - string
          - 'null'
        userId:
          type:
          - string
          - 'null'
        input: {}
        output: {}
        sessionId:
          type:
          - string
          - 'null'
        release:
          type:
          - string
          - 'null'
        version:
          type:
          - string
          - 'null'
        metadata: {}
        tags:
          type:
          - array
          - 'null'
          items:
            type: string
        environment:
          type:
          - string
          - 'null'
        public:
          type:
          - boolean
          - 'null'
          description: Make trace publicly accessible via url
    CreateGenerationEvent:
      title: CreateGenerationEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/CreateGenerationBody'
      required:
      - body
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
    CreateSpanEvent:
      title: CreateSpanEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/CreateSpanBody'
      required:
      - body
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
    IngestionEvent:
      title: IngestionEvent
      oneOf:
      - type: object
        allOf:
        - type: object
          properties:
            type:
              type: string
              enum:
              - trace-create
        - $ref: '#/components/schemas/TraceEvent'
        required:
        - type
      - type: object
        allOf:
        - type: object
          properties:
            type:
              type: string
              enum:
              - score-create
        - $ref: '#/components/schemas/ScoreEvent'
        required:
        - type
      - type: object
        allOf:
        - type: object
          properties:
            type:
              type: string
              enum:
              - span-create
        - $ref: '#/components/schemas/CreateSpanEvent'
        required:
        - type
      - type: object
        allOf:
        - type: object
          properties:
            type:
              type: string
              enum:
              - span-update
        - $ref: '#/components/schemas/UpdateSpanEvent'
        required:
        - type
      - type: object
        allOf:
        - type: object
          properties:
            type:
              type: string
              enum:
              - generation-create
        - $ref: '#/components/schemas/CreateGenerationEvent'
        required:
        - type
      - type: object
        allOf:
        - type: object
          properties:
            type:
              type: string
              enum:
              - generation-update
        - $ref: '#/components/schemas/UpdateGenerationEvent'
        required:
        - type
      - type: object
        allOf:
        - type: object
          properties:
            type:
              type: string
              enum:
              - event-create
        - $ref: '#/components/schemas/CreateEventEvent'
        required:
        - type
      - type: object
        allOf:
        - type: object
          properties:
            type:
              type: string
              enum:
              - sdk-log
        - $ref: '#/components/schemas/SDKLogEvent'
        required:
        - type
      - type: object
        allOf:
        - type: object
          properties:
            type:
              type: string
              enum:
              - observation-create
        - $ref: '#/components/schemas/CreateObservationEvent'
        required:
        - type
      - type: object
        allOf:
        - type: object
          properties:
            type:
              type: string
              enum:
              - observation-update
        - $ref: '#/components/schemas/UpdateObservationEvent'
        required:
        - type
    UpdateSpanBody:
      title: UpdateSpanBody
      type: object
      properties:
        endTime:
          type:
          - string
          - 'null'
          format: date-time
      allOf:
      - $ref: '#/components/schemas/UpdateEventBody'
    IngestionUsage:
      title: IngestionUsage
      oneOf:
      - $ref: '#/components/schemas/Usage'
      - $ref: '#/components/schemas/OpenAIUsage'
    CreateObservationEvent:
      title: CreateObservationEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/ObservationBody'
      required:
      - body
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
    ScoreDataType:
      title: ScoreDataType
      type: string
      enum:
      - NUMERIC
      - BOOLEAN
      - CATEGORICAL
      - CORRECTION
      - TEXT
    TraceEvent:
      title: TraceEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/TraceBody'
      required:
      - body
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
    ObservationBody:
      title: ObservationBody
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        traceId:
          type:
          - string
          - 'null'
        type:
          $ref: '#/components/schemas/ObservationType'
        name:
          type:
          - string
          - 'null'
        startTime:
          type:
          - string
          - 'null'
          format: date-time
        endTime:
          type:
          - string
          - 'null'
          format: date-time
        completionStartTime:
          type:
          - string
          - 'null'
          format: date-time
        model:
          type:
          - string
          - 'null'
        modelParameters:
          type:
          - object
          - 'null'
          additionalProperties:
            $ref: '#/components/schemas/MapValue'
        input: {}
        version:
          type:
          - string
          - 'null'
        metadata: {}
        output: {}
        usage:
          $ref: '#/components/schemas/Usage'
        level:
          $ref: '#/components/schemas/ObservationLevel'
        statusMessage:
          type:
          - string
          - 'null'
        parentObservationId:
          type:
          - string
          - 'null'
        environment:
          type:
          - string
          - 'null'
      required:
      - type
    CreateEventEvent:
      title: CreateEventEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/CreateEventBody'
      required:
      - body
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
    IngestionResponse:
      title: IngestionResponse
      type: object
      properties:
        successes:
          type: array
          items:
            $ref: '#/components/schemas/IngestionSuccess'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/IngestionError'
      required:
      - successes
      - errors
    UpdateSpanEvent:
      title: UpdateSpanEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/UpdateSpanBody'
      required:
      - body
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
    OpenAIResponseUsageSchema:
      title: OpenAIResponseUsageSchema
      type: object
      description: OpenAI Usage schema from Response API
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        total_tokens:
          type: integer
        input_tokens_details:
          type:
          - object
          - 'null'
          additionalProperties:
            type:
            - integer
            - 'null'
        output_tokens_details:
          type:
          - object
          - 'null'
          additionalProperties:
            type:
            - integer
            - 'null'
      required:
      - input_tokens
      - output_tokens
      - total_tokens
    CreateSpanBody:
      title: CreateSpanBody
      type: object
      properties:
        endTime:
          type:
          - string
          - 'null'
          format: date-time
      allOf:
      - $ref: '#/components/schemas/CreateEventBody'
    OpenAIUsage:
      title: OpenAIUsage
      type: object
      description: Usage interface of OpenAI for improved compatibility.
      properties:
        promptTokens:
          type:
          - integer
          - 'null'
        completionTokens:
          type:
          - integer
          - 'null'
        totalTokens:
          type:
          - integer
          - 'null'
    OptionalObservationBody:
      title: OptionalObservationBody
      type: object
      properties:
        traceId:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
        startTime:
          type:
          - string
          - 'null'
          format: date-time
        metadata: {}
        input: {}
        output: {}
        level:
          $ref: '#/components/schemas/ObservationLevel'
        statusMessage:
          type:
          - string
          - 'null'
        parentObservationId:
          type:
          - string
          - 'null'
        version:
          type:
          - string
          - 'null'
        environment:
          type:
          - string
          - 'null'
    CreateEventBody:
      title: CreateEventBody
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
      allOf:
      - $ref: '#/components/schemas/OptionalObservationBody'
    OpenAICompletionUsageSchema:
      title: OpenAICompletionUsageSchema
      type: object
      description: OpenAI Usage schema from (Chat-)Completion APIs
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
        prompt_tokens_details:
          type:
          - object
          - 'null'
          additionalProperties:
            type:
            - integer
            - 'null'
        completion_tokens_details:
          type:
          - object
          - 'null'
          additionalProperties:
            type:
            - integer
            - 'null'
      required:
      - prompt_tokens
      - completion_tokens
      - total_tokens
    SDKLogEvent:
      title: SDKLogEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/SDKLogBody'
      required:
      - body
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
    SDKLogBody:
      title: SDKLogBody
      type: object
      properties:
        log: {}
      required:
      - log
    ObservationLevel:
      title: ObservationLevel
      type: string
      enum:
      - DEBUG
      - DEFAULT
      - WARNING
      - ERROR
    IngestionError:
      title: IngestionError
      type: object
      properties:
        id:
          type: string
        status:
          type: integer
        message:
          type:
          - string
          - 'null'
        error: {}
      required:
      - id
      - status
    UpdateGenerationBody:
      title: UpdateGenerationBody
      type: object
      properties:
        completionStartTime:
          type:
          - string
          - 'null'
          format: date-time
        model:
          type:
          - string
          - 'null'
        modelParameters:
          type:
          - object
          - 'null'
          additionalProperties:
            $ref: '#/components/schemas/MapValue'
        usage:
          $ref: '#/components/schemas/IngestionUsage'
        promptName:
          type:
          - string
          - 'null'
        usageDetails:
          $ref: '#/components/schemas/UsageDetails'
        costDetails:
          type:
          - object
          - 'null'
          additionalProperties:
            type: number
            format: double
        promptVersion:
          type:
          - integer
          - 'null'
      allOf:
      - $ref: '#/components/schemas/UpdateSpanBody'
    BaseEvent:
      title: BaseEvent
      type: object
      properties:
        id:
          type: string
          description: UUID v4 that identifies the event
        timestamp:
          type: string
          description: 'Datetime (ISO 8601) of event creation in client. Should be as close to actual event creation in client as possible, this timestamp will be used for ordering of events in future release. Resolution: milliseconds (required), microseconds (optimal).'
        metadata:
          description: Optional. Metadata field used by the Langfuse SDKs for debugging.
      required:
      - id
      - timestamp
    ScoreBody:
      title: ScoreBody
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        traceId:
          type:
          - string
          - 'null'
        sessionId:
          type:
          - string
          - 'null'
        observationId:
          type:
          - string
          - 'null'
        datasetRunId:
          type:
          - string
          - 'null'
        name:
          type: string
          description: The name of the score. Always overrides "output" for correction scores.
          example: novelty
        environment:
          type:
          - string
          - 'null'
        queueId:
          type:
          - string
          - 'null'
          description: The annotation queue referenced by the score. Indicates if score was initially created while processing annotation queue.
        value:
          $ref: '#/components/schemas/CreateScoreValue'
          description: The value of the score. Must be passed as string for categorical and text scores, and numeric for boolean and numeric scores. Boolean score values must equal either 1 or 0 (true or false). Text score values must be between 1 and 500 characters.
        comment:
          type:
          - string
          - 'null'
        metadata: {}
        dataType:
          $ref: '#/components/schemas/ScoreDataType'
          description: When set, must match the score value's type. If not set, will be inferred from the score value or config
        configId:
          type:
          - string
          - 'null'
          description: Reference a score config on a score. When set, the score name must equal the config name and scores must comply with the config's range and data type. For categorical scores, the value must map to a config category. Numeric scores might be constrained by the score config's max and min values
      required:
      - name
      - value
    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
          - 'null'
          description: Unit of measurement
        inputCost:
          type:
          - number
          - 'null'
          format: double
          description: USD input cost
        outputCost:
          type:
          - number
          - 'null'
          format: double
          description: USD output cost
        totalCost:
          type:
          - number
          - 'null'
          format: double
          description: USD total cost, defaults to input+output
      required:
      - input
      - output
      - total
    UpdateGenerationEvent:
      title: UpdateGenerationEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/UpdateGenerationBody'
      required:
      - body
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
    UpdateObservationEvent:
      title: UpdateObservationEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/ObservationBody'
      required:
      - body
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic