openapi: 3.0.1
info:
  title: AI Gateway API
  version: '1.0'
servers:
  - url: https://api.us-east-1.langdb.ai
    description: LangDB API Server
paths:
  /analytics:
    post:
      tags:
        - Analytics
      summary: Fetch analytics data
      parameters:
        - $ref: '#/components/parameters/XProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start_time_us:
                  type: integer
                  format: int64
                  description: "Start time in microseconds."
                  example: 1693062345678
                  deprecated: true
                end_time_us:
                  type: integer
                  format: int64
                  description: "End time in microseconds."
                  example: 1693082345678
                  deprecated: true
                period:
                  type: string
                  description: "Time period for filtering data. If provided, start_time and end_time will be ignored."
                  enum: [last_minute, last15_minute, last_15_minutes, last_hour, last3_hours, last_3_hours, last12_hours, last_12_hours, last_day, last_week, last_month, last_year]
                  example: "last_month"

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsResponse'
      security:
        - BearerAuth: []


  /analytics/summary:
    post:
      tags:
        - Analytics
      summary: Fetch analytics summary
      parameters:
        - $ref: '#/components/parameters/XProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - groupBy
              properties:
                start_time_us:
                  type: integer
                  format: int64
                  example: 1693062345678
                  deprecated: true
                end_time_us:
                  type: integer
                  format: int64
                  example: 1693082345678
                  deprecated: true
                period:
                  type: string
                  description: "Time period for filtering data. If provided, start_time and end_time will be ignored."
                  enum: [last_minute, last15_minute, last_15_minutes, last_hour, last3_hours, last_3_hours, last12_hours, last_12_hours, last_day, last_week, last_month, last_year]
                  example: "last_month"
                groupBy:
                  type: array
                  items:
                    type: string
                  example: ["provider"]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSummaryResponse'
      security:
        - BearerAuth: []
  /usage/total:
    post:
      tags:
        - Analytics
      summary: Get total usage
      parameters:
        - $ref: '#/components/parameters/XProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start_time_us:
                  type: integer
                  format: int64
                  example: 1693062345678
                  deprecated: true
                end_time_us:
                  type: integer
                  format: int64
                  description: "End time in microseconds."
                  example: 1693082345678
                  deprecated: true
                period:
                  type: string
                  description: "Time period for filtering data. If provided, start_time and end_time will be ignored."
                  enum: [last_minute, last15_minute, last_15_minutes, last_hour, last3_hours, last_3_hours, last12_hours, last_12_hours, last_day, last_week, last_month, last_year]
                  example: "last_month"

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TotalUsageResponse'
      security:
        - BearerAuth: []


  /usage/models:
    post:
      tags:
        - Analytics
      summary: Get usage by model
      parameters:
        - $ref: '#/components/parameters/XProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start_time_us:
                  type: integer
                  format: int64
                  example: 1693062345678
                end_time_us:
                  type: integer
                  format: int64
                min_unit:
                  type: string
                  enum: [hour, day, month]
                  description: "The granularity of the returned usage data."
                  example: hour
  
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GranularUsageResponse'
      security:
        - BearerAuth: []


components:
  parameters:
    XProjectId:
      name: X-Project-Id
      in: header
      description: "LangDB project ID"
      required: true
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    AnalyticsResponse:
      type: object
      required:
        - timeseries
        - start_time_us
        - end_time_us
      properties:
        timeseries:
          type: array
          description: "An array of analytics timeseries records."
          items:
            type: object
            required:
              - hour
              - total_cost
              - total_requests
              - avg_duration
              - duration
              - duration_p99
              - duration_p95
              - duration_p90
              - duration_p50
              - total_duration
              - total_input_tokens
              - total_output_tokens
              - error_rate
              - error_request_count
              - avg_ttft
              - ttft
              - ttft_p99
              - ttft_p95
              - ttft_p90
              - ttft_p50
              - tps
              - tps_p99
              - tps_p95
              - tps_p90
              - tps_p50
              - tpot
              - tpot_p99
              - tpot_p95
              - tpot_p90
              - tpot_p50
              - tag_tuple
            properties:
              hour:
                type: string
                description: "The timestamp for the record (e.g. 'YYYY-MM-DD HH:mm:ss')."
                example: "2025-02-20 18:00:00"
              total_cost:
                type: number
                format: double
                description: "Total cost incurred during this period."
                example: 12.34
              total_requests:
                type: integer
                description: "Total number of requests."
                example: 1000
              avg_duration:
                type: number
                format: double
                description: "Average duration (in milliseconds) of requests."
                example: 250.5
              duration:
                type: number
                format: double
                description: "Duration (in milliseconds) of requests."
                example: 245.7
              duration_p99:
                type: number
                format: double
                description: "99th percentile of request durations."
                example: 750.2
              duration_p95:
                type: number
                format: double
                description: "95th percentile of request durations."
                example: 500.1
              duration_p90:
                type: number
                format: double
                description: "90th percentile of request durations."
                example: 400.8
              duration_p50:
                type: number
                format: double
                description: "50th percentile of request durations."
                example: 200.3
              total_duration:
                type: number
                format: double
                description: "Total duration (in milliseconds) of all requests."
              total_input_tokens:
                type: integer
                description: "Total number of input tokens used."
              total_output_tokens:
                type: integer
                description: "Total number of output tokens generated."
              error_rate:
                type: number
                format: double
                description: "Error rate (as a percentage) over the period."
              error_request_count:
                type: integer
                description: "Number of error requests."
              avg_ttft:
                type: number
                format: double
                description: "Average time to first byte (TTFT) in milliseconds."
              ttft:
                type: number
                format: double
                description: "Time to first byte (TTFT) in milliseconds."
              ttft_p99:
                type: number
                format: double
                description: "99th percentile of TTFT."
              ttft_p95:
                type: number
                format: double
                description: "95th percentile of TTFT."
              ttft_p90:
                type: number
                format: double
                description: "90th percentile of TTFT."
              ttft_p50:
                type: number
                format: double
                description: "50th percentile of TTFT."
              tps:
                type: number
                format: double
                description: "Transactions per second."
              tps_p99:
                type: number
                format: double
                description: "99th percentile TPS."
              tps_p95:
                type: number
                format: double
                description: "95th percentile TPS."
              tps_p90:
                type: number
                format: double
                description: "90th percentile TPS."
              tps_p50:
                type: number
                format: double
                description: "50th percentile TPS."
              tpot:
                type: number
                format: double
                description: "Average transactions per output token (Tpot)."
                example: 0.85
              tpot_p99:
                type: number
                format: double
                description: "99th percentile of Tpot."
                example: 1.5
              tpot_p95:
                type: number
                format: double
                description: "95th percentile of Tpot."
                example: 1.2
              tpot_p90:
                type: number
                format: double
                description: "90th percentile of Tpot."
                example: 1.0
              tpot_p50:
                type: number
                format: double
                description: "50th percentile of Tpot."
                example: 0.75
              tag_tuple:
                type: array
                items:
                  type: string
                description: "A tuple of tags associated with the record."
        start_time:
          type: integer
          format: int64
          description: "Start time in seconds since epoch."
        end_time:
          type: integer
          format: int64
          description: "End time in seconds since epoch."
        start_time_us:
          type: integer
          format: int64
          description: "Start time in microseconds since epoch. Deprecated, use start_time instead."
          deprecated: true
        end_time_us:
          type: integer
          format: int64
          description: "End time in microseconds since epoch. Deprecated, use end_time instead."
          deprecated: true

    AnalyticsSummaryItem:
      type: object
      required:
        - tag_tuple
        - total_cost
        - total_requests
        - total_duration
        - avg_duration
        - duration
        - duration_p99
        - duration_p95
        - duration_p90
        - duration_p50
        - total_input_tokens
        - total_output_tokens
        - avg_ttft
        - ttft
        - ttft_p99
        - ttft_p95
        - ttft_p90
        - ttft_p50
        - tps
        - tps_p99
        - tps_p95
        - tps_p90
        - tps_p50
        - tpot
        - tpot_p99
        - tpot_p95
        - tpot_p90
        - tpot_p50
        - error_rate
        - error_request_count
      properties:
        tag_tuple:
          type: array
          items:
            type: string
          description: >
            The grouping key(s) used for this summary. In this example the key is returned as tag_tuple.
            (Depending on the groupBy parameter, this field might contain provider names or model names.)
          example: ["openai", "gpt-4"]
        total_cost:
          type: number
          format: double
          description: "Aggregated total cost in USD for the group."
          example: 156.78
        total_requests:
          type: integer
          description: "Aggregated total number of requests for the group."
          example: 5000
        total_duration:
          type: number
          format: double
          description: "Aggregated total duration (in milliseconds) for the group."
          example: 1250000.0
        avg_duration:
          type: number
          format: double
          description: "Average duration (in milliseconds) of requests for the group."
          example: 250.0
        duration:
          type: number
          format: double
          description: "Representative duration (in milliseconds) for the group."
          example: 245.5
        duration_p99:
          type: number
          format: double
          description: "99th percentile of request durations."
          example: 750.0
        duration_p95:
          type: number
          format: double
          description: "95th percentile of request durations."
          example: 500.0
        duration_p90:
          type: number
          format: double
          description: "90th percentile of request durations."
          example: 400.0
        duration_p50:
          type: number
          format: double
          description: "50th percentile of request durations."
          example: 200.0
        total_input_tokens:
          type: integer
          description: "Aggregated total input tokens used in the group."
          example: 100000
        total_output_tokens:
          type: integer
          description: "Aggregated total output tokens generated in the group."
          example: 50000
        avg_ttft:
          type: number
          format: double
          description: "Average time-to-first-byte (TTFT) in milliseconds for the group."
          example: 100.0
        ttft:
          type: number
          format: double
          description: "Representative TTFT value in milliseconds for the group."
          example: 98.5
        ttft_p99:
          type: number
          format: double
          description: "99th percentile of TTFT."
          example: 300.0
        ttft_p95:
          type: number
          format: double
          description: "95th percentile of TTFT."
          example: 200.0
        ttft_p90:
          type: number
          format: double
          description: "90th percentile of TTFT."
          example: 150.0
        ttft_p50:
          type: number
          format: double
          description: "50th percentile of TTFT."
          example: 80.0
        tps:
          type: number
          format: double
          description: "Aggregated transactions per second (TPS) for the group."
          example: 10.5
        tps_p99:
          type: number
          format: double
          description: "99th percentile of TPS."
          example: 20.0
        tps_p95:
          type: number
          format: double
          description: "95th percentile of TPS."
          example: 15.0
        tps_p90:
          type: number
          format: double
          description: "90th percentile of TPS."
          example: 12.0
        tps_p50:
          type: number
          format: double
          description: "50th percentile of TPS."
          example: 8.0
        tpot:
          type: number
          format: double
          description: "Aggregated average transactions per output token (TPOT) for the group."
          example: 0.85
        tpot_p99:
          type: number
          format: double
          description: "99th percentile of TPOT."
          example: 1.5
        tpot_p95:
          type: number
          format: double
          description: "95th percentile of TPOT."
          example: 1.2
        tpot_p90:
          type: number
          format: double
          description: "90th percentile of TPOT."
          example: 1.0
        tpot_p50:
          type: number
          format: double
          description: "50th percentile of TPOT."
          example: 0.75
        error_rate:
          type: number
          format: double
          description: "Error rate (as a percentage) for the group."
        error_request_count:
          type: integer
          description: "Total number of error requests in the group."

    AnalyticsSummaryResponse:
      type: object
      required:
        - summary
        - start_time_us
        - end_time_us
      properties:
        summary:
          type: array
          description: "An array of aggregated analytics summary records."
          items:
            $ref: '#/components/schemas/AnalyticsSummaryItem'
        start_time:
          type: integer
          format: int64
          description: "Start time in seconds since epoch."
        end_time:
          type: integer
          format: int64
          description: "End time in seconds since epoch."
        start_time_us:
          type: integer
          format: int64
          description: "Start time in microseconds since epoch. Deprecated, use start_time instead."
          deprecated: true
        end_time_us:
          type: integer
          format: int64
          description: "End time in microseconds since epoch. Deprecated, use end_time instead."
          deprecated: true
    TotalUsageResponse:
      type: object
      properties:
        models:
          type: array
          items:
            type: object
            properties:
              provider:
                type: string
                example: openai
              model_name:
                type: string
                example: gpt-4o
              total_input_tokens:
                type: integer
                example: 3196182
              total_output_tokens:
                type: integer
                example: 74096
              total_cost:
                type: number
                format: float
                example: 10.4776979999
              cost_per_input_token:
                type: number
                format: float
                example: 3.0
              cost_per_output_token:
                type: number
                format: float
                example: 12.0
        total:
          type: object
          properties:
            total_input_tokens:
              type: integer
              example: 4181386
            total_output_tokens:
              type: integer
              example: 206547
            total_cost:
              type: number
              format: float
              example: 11.8904386859
        period_start:
          type: integer
          format: int64
          description: "Start of the period in seconds since epoch."
          example: 1737504000
        period_end:
          type: integer
          format: int64
          description: "End of the period in seconds since epoch."
          example: 1740120949
        period_start_us:
          type: integer
          format: int64
          description: "Start of the period in microseconds since epoch. Deprecated, use period_start instead."
          example: 1737504000000000
          deprecated: true
        period_end_us:
          type: integer
          format: int64
          description: "End of the period in microseconds since epoch. Deprecated, use period_end instead."
          example: 1740120949421000
          deprecated: true
      required:
        - models
        - total
        - period_start
        - period_end

    GranularModelUsage:
      type: object
      required:
        - time
        - provider
        - model_name
        - total_input_tokens
        - total_output_tokens
        - total_cost
      properties:
        time:
          type: string
          description: >
            The timestamp corresponding to the usage data. The format depends on the requested granularity:
            - Hourly: "YYYY-MM-DD HH:mm:ss"
            - Daily: "YYYY-MM-DD"
            - Monthly: "YYYY-MM"
        provider:
          type: string
          description: "The provider of the model (e.g. openai, gemini, etc.)"
        model_name:
          type: string
          description: "The name of the model"
        total_input_tokens:
          type: integer
          description: "Total number of input tokens used"
        total_output_tokens:
          type: integer
          description: "Total number of output tokens generated"
        total_cost:
          type: number
          format: double
          description: "Total cost in USD"
    GranularUsageResponse:
      type: object
      properties:
        models:
          type: array
          description: "Usage statistics for each model at the specified granularity (hourly, daily, or monthly)"
          items:
            type: object
            properties:
              hour:
                type: string
                description: "Timestamp for the record"
                example: "2025-02-15 09:00:00"
              provider:
                type: string
                example: "openai"
              model_name:
                type: string
                example: "gpt-4o"
              total_input_tokens:
                type: integer
                example: 451235
              total_output_tokens:
                type: integer
                example: 2553
              total_cost:
                type: number
                format: float
                example: 1.3843410000000005
        period_start:
          type: integer
          format: int64
          description: "Start of the usage period in microseconds since epoch"
          example: 1737504000000000
        period_end:
          type: integer
          format: int64
          description: "End of the usage period in microseconds since epoch"
          example: 1740121147931000
      required:
        - models
        - period_start
        - period_end
    TotalUsageSummary:
      type: object
      required:
        - total_input_tokens
        - total_output_tokens
        - total_cost
      properties:
        total_input_tokens:
          type: integer
          description: Total input tokens across all models
        total_output_tokens:
          type: integer
          description: Total output tokens across all models
        total_cost:
          type: number
          format: double
          description: Total cost across all models in USD

    ModelUsage:
      type: object
      required:
        - provider
        - model_name
        - total_input_tokens
        - total_output_tokens
        - total_cost
        - cost_per_input_token
        - cost_per_output_token
        
    TimeFilter:
      type: object
      properties:
        start_time:
          type: integer
          format: int64
          description: "Start time in seconds."
        end_time:
          type: integer
          format: int64
          description: "End time in seconds."
        period:
          type: string
          description: "Time period for filtering data. If provided, start_time and end_time will be ignored."
          enum: [last_minute, last15_minute, last_15_minutes, last_hour, last3_hours, last_3_hours, last12_hours, last_12_hours, last_day, last_week, last_month, last_year]