# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json
imports:
  commons: ./commons.yml
  pagination: ./utils/pagination.yml
service:
  auth: true
  base-path: /api/public
  endpoints:
    get:
      docs: Get a observation
      method: GET
      path: /observations/{observationId}
      path-parameters:
        observationId:
          type: string
          docs: The unique langfuse identifier of an observation, can be an event, span or generation
      response: commons.ObservationsView
    getMany:
      docs: |
        Get a list of observations.

        Consider using the [v2 observations endpoint](/api-reference#tag/observationsv2/GET/api/public/v2/observations) for cursor-based pagination and field selection.
      method: GET
      path: /observations
      request:
        name: GetObservationsRequest
        query-parameters:
          page:
            type: optional<integer>
            docs: Page number, starts at 1.
          limit:
            type: optional<integer>
            docs: Limit of items per page. If you encounter api issues due to too large page sizes, try to reduce the limit.
          name: optional<string>
          userId: optional<string>
          type: optional<string>
          traceId: optional<string>
          level:
            type: optional<commons.ObservationLevel>
            docs: Optional filter for observations with a specific level (e.g. "DEBUG", "DEFAULT", "WARNING", "ERROR").
          parentObservationId: optional<string>
          environment:
            type: optional<string>
            allow-multiple: true
            docs: Optional filter for observations where the environment is one of the provided values.
          fromStartTime:
            type: optional<datetime>
            docs: Retrieve only observations with a start_time on or after this datetime (ISO 8601).
          toStartTime:
            type: optional<datetime>
            docs: Retrieve only observations with a start_time before this datetime (ISO 8601).
          version:
            type: optional<string>
            docs: Optional filter to only include observations with a certain version.
          filter:
            type: optional<string>
            docs: |
              JSON string containing an array of filter conditions. When provided, this takes precedence over query parameter filters (userId, name, type, level, environment, fromStartTime, ...).

              ## Filter Structure
              Each filter condition has the following structure:
              ```json
              [
                {
                  "type": string,           // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
                  "column": string,         // Required. Column to filter on (see available columns below)
                  "operator": string,       // Required. Operator based on type:
                                            // - datetime: ">", "<", ">=", "<="
                                            // - string: "=", "contains", "does not contain", "starts with", "ends with"
                                            // - stringOptions: "any of", "none of"
                                            // - categoryOptions: "any of", "none of"
                                            // - arrayOptions: "any of", "none of", "all of"
                                            // - number: "=", ">", "<", ">=", "<="
                                            // - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
                                            // - numberObject: "=", ">", "<", ">=", "<="
                                            // - boolean: "=", "<>"
                                            // - null: "is null", "is not null"
                  "value": any,             // Required (except for null type). Value to compare against. Type depends on filter type
                  "key": string             // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
                }
              ]
              ```

              ## Available Columns

              ### Core Observation Fields
              - `id` (string) - Observation ID
              - `type` (string) - Observation type (SPAN, GENERATION, EVENT)
              - `name` (string) - Observation name
              - `traceId` (string) - Associated trace ID
              - `startTime` (datetime) - Observation start time
              - `endTime` (datetime) - Observation end time
              - `environment` (string) - Environment tag
              - `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)
              - `statusMessage` (string) - Status message
              - `version` (string) - Version tag

              ### Performance Metrics
              - `latency` (number) - Latency in seconds (calculated: end_time - start_time)
              - `timeToFirstToken` (number) - Time to first token in seconds
              - `tokensPerSecond` (number) - Output tokens per second

              ### Token Usage
              - `inputTokens` (number) - Number of input tokens
              - `outputTokens` (number) - Number of output tokens
              - `totalTokens` (number) - Total tokens (alias: `tokens`)

              ### Cost Metrics
              - `inputCost` (number) - Input cost in USD
              - `outputCost` (number) - Output cost in USD
              - `totalCost` (number) - Total cost in USD

              ### Model Information
              - `model` (string) - Provided model name
              - `promptName` (string) - Associated prompt name
              - `promptVersion` (number) - Associated prompt version

              ### Structured Data
              - `metadata` (stringObject/numberObject/categoryOptions) - Metadata key-value pairs. Use `key` parameter to filter on specific metadata keys.

              ### Associated Trace Fields (requires join with traces table)
              - `userId` (string) - User ID from associated trace
              - `traceName` (string) - Name from associated trace
              - `traceEnvironment` (string) - Environment from associated trace
              - `traceTags` (arrayOptions) - Tags from associated trace

              ## Filter Examples
              ```json
              [
                {
                  "type": "string",
                  "column": "type",
                  "operator": "=",
                  "value": "GENERATION"
                },
                {
                  "type": "number",
                  "column": "latency",
                  "operator": ">=",
                  "value": 2.5
                },
                {
                  "type": "stringObject",
                  "column": "metadata",
                  "key": "environment",
                  "operator": "=",
                  "value": "production"
                }
              ]
              ```
      response: ObservationsViews

types:
  Observations:
    properties:
      data: list<commons.Observation>
      meta: pagination.MetaResponse

  ObservationsViews:
    properties:
      data: list<commons.ObservationsView>
      meta: pagination.MetaResponse