> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get usage analytics

> Use when building analytics views (e.g. usage by feature or customer over time). Supports filtering, grouping, and time-series breakdown.



## OpenAPI

````yaml /api-reference/openapi.json post /events/analytics
openapi: 3.0.1
info:
  title: Flexprice API
  description: Flexprice API Service
  contact:
    name: API Support
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
  version: '1.0'
servers:
  - url: https://us.api.flexprice.io/v1
    description: US Region
  - url: https://api.cloud.flexprice.io/v1
    description: India Region
security: []
paths:
  /events/analytics:
    post:
      tags:
        - Events
      summary: Get usage analytics
      description: >-
        Use when building analytics views (e.g. usage by feature or customer
        over time). Supports filtering, grouping, and time-series breakdown.
      operationId: getUsageAnalytics
      requestBody:
        description: Request body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetUsageAnalyticsRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUsageAnalyticsResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    GetUsageAnalyticsRequest:
      type: object
      properties:
        end_time:
          type: string
          format: date-time
        expand:
          type: array
          description: >-
            allowed values: "price", "meter", "feature",
            "subscription_line_item","plan","addon"
          items:
            type: string
        external_customer_id:
          type: string
          description: |-
            ExternalCustomerID is the single external customer ID.
            Optional when ExternalCustomerIDs is provided; required otherwise.
        feature_ids:
          type: array
          items:
            type: string
        group_by:
          type: array
          description: 'allowed values: "source", "feature_id", "properties.<field_name>"'
          items:
            type: string
        include_children:
          type: boolean
          description: >-
            IncludeChildren when true folds child customers' usage into the
            single aggregated total.

            Default: false.
        property_filters:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: >-
            Property filters to filter the events by the keys in `properties`
            field of the event
        sources:
          type: array
          items:
            type: string
        start_time:
          type: string
          format: date-time
        window_size:
          $ref: '#/components/schemas/types.WindowSize'
    GetUsageAnalyticsResponse:
      type: object
      properties:
        currency:
          type: string
        custom_analytics:
          type: array
          items:
            $ref: '#/components/schemas/CustomAnalyticItem'
        items:
          type: array
          items:
            $ref: '#/components/schemas/UsageAnalyticItem'
        total_cost:
          type: string
    errors.ErrorResponse:
      type: object
      properties:
        code:
          type: string
          enum:
            - not_found
            - already_exists
            - version_conflict
            - validation_error
            - invalid_operation
            - permission_denied
            - http_client_error
            - database_error
            - system_error
            - internal_error
            - service_unavailable
        details:
          type: object
          additionalProperties:
            type: object
        http_status_code:
          type: integer
        message:
          type: string
      x-speakeasy-name-override: ErrorResponse
    types.WindowSize:
      type: string
      enum:
        - MINUTE
        - 15MIN
        - 30MIN
        - HOUR
        - 3HOUR
        - 6HOUR
        - 12HOUR
        - DAY
        - WEEK
        - MONTH
        - MONTH
      x-enum-varnames:
        - WindowSizeMinute
        - WindowSize15Min
        - WindowSize30Min
        - WindowSizeHour
        - WindowSize3Hour
        - WindowSize6Hour
        - WindowSize12Hour
        - WindowSizeDay
        - WindowSizeWeek
        - WindowSizeMonth
        - DefaultWindowSize
      x-speakeasy-name-override: WindowSize
    CustomAnalyticItem:
      type: object
      properties:
        feature_name:
          type: string
          description: Name of the feature this applies to
        id:
          type: string
        name:
          type: string
          description: Calculation name (e.g., "Revenue per Minute")
        type:
          type: string
          description: '"feature", "meter", "event_name"'
        value:
          type: string
    UsageAnalyticItem:
      type: object
      properties:
        add_on_id:
          type: string
        addon:
          $ref: '#/components/schemas/Addon'
        aggregation_type:
          $ref: '#/components/schemas/types.AggregationType'
        commitment_info:
          $ref: '#/components/schemas/types.CommitmentInfo'
        currency:
          type: string
        event_count:
          type: integer
          description: Number of events that contributed to this aggregation
        event_name:
          type: string
        feature:
          $ref: '#/components/schemas/Feature'
        feature_id:
          type: string
        group:
          $ref: '#/components/schemas/group.Group'
        meter:
          $ref: '#/components/schemas/meter.Meter'
        meter_id:
          type: string
          description: Meter ID
        name:
          type: string
        plan:
          $ref: '#/components/schemas/Plan'
        plan_id:
          type: string
        points:
          type: array
          items:
            $ref: '#/components/schemas/UsageAnalyticPoint'
        price:
          $ref: '#/components/schemas/PriceResponse'
        price_id:
          type: string
          description: Price ID used for this usage
        properties:
          type: object
          additionalProperties:
            type: string
          description: >-
            Stores property values for flexible grouping (e.g., org_id ->
            "org123")
        reporting_unit:
          $ref: '#/components/schemas/types.ReportingUnit'
        source:
          type: string
        sources:
          type: array
          description: List of sources when not grouping by source
          items:
            type: string
        sub_line_item_id:
          type: string
          description: Subscription line item ID
        subscription_id:
          type: string
          description: Subscription ID
        subscription_line_item:
          $ref: '#/components/schemas/subscription.SubscriptionLineItem'
        total_cost:
          type: string
        total_usage:
          type: string
        total_usage_display:
          type: string
          description: >-
            Empty string when feature has no reporting unit; otherwise the value
            in reporting units
        unit:
          type: string
        unit_plural:
          type: string
        window_size:
          $ref: '#/components/schemas/types.WindowSize'
    Addon:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        description:
          type: string
        environment_id:
          type: string
        id:
          type: string
        lookup_key:
          type: string
        metadata:
          type: object
          additionalProperties: true
        name:
          type: string
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.AggregationType:
      type: string
      enum:
        - COUNT
        - SUM
        - AVG
        - COUNT_UNIQUE
        - LATEST
        - SUM_WITH_MULTIPLIER
        - MAX
        - WEIGHTED_SUM
      x-enum-comments:
        AggregationSumWithMultiplier: Sum with a multiplier - [sum(value) * multiplier]
      x-enum-varnames:
        - AggregationCount
        - AggregationSum
        - AggregationAvg
        - AggregationCountUnique
        - AggregationLatest
        - AggregationSumWithMultiplier
        - AggregationMax
        - AggregationWeightedSum
      x-speakeasy-name-override: AggregationType
    types.CommitmentInfo:
      type: object
      properties:
        amount:
          type: string
        computed_commitment_utilized_amount:
          type: string
        computed_overage_amount:
          type: string
        computed_true_up_amount:
          type: string
          description: >-
            total_cost = computed_commitment_utilized_amount +
            computed_overage_amount + computed_true_up_amount
        duration:
          $ref: '#/components/schemas/types.BillingPeriod'
        is_windowed:
          type: boolean
        overage_factor:
          type: string
        quantity:
          type: string
          description: Only used for quantity-based commitments
        true_up_enabled:
          type: boolean
        type:
          $ref: '#/components/schemas/types.CommitmentType'
      x-speakeasy-name-override: CommitmentInfo
    Feature:
      type: object
      properties:
        alert_settings:
          $ref: '#/components/schemas/types.AlertSettings'
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        description:
          type: string
        environment_id:
          type: string
        group:
          $ref: '#/components/schemas/group.Group'
        group_id:
          type: string
        id:
          type: string
        lookup_key:
          type: string
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        meter_id:
          type: string
        name:
          type: string
        reporting_unit:
          $ref: '#/components/schemas/types.ReportingUnit'
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        type:
          $ref: '#/components/schemas/types.FeatureType'
        unit_plural:
          type: string
        unit_singular:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    group.Group:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        entity_type:
          $ref: '#/components/schemas/types.GroupEntityType'
        environment_id:
          type: string
        id:
          type: string
        lookup_key:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        name:
          type: string
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    meter.Meter:
      type: object
      properties:
        aggregation:
          $ref: '#/components/schemas/meter.Aggregation'
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        environment_id:
          type: string
          description: EnvironmentID is the environment identifier for the meter
        event_name:
          type: string
          description: >-
            EventName is the unique identifier for the event that this meter is
            tracking

            It is a mandatory field in the events table and hence being used as
            the primary matching field

            We can have multiple meters tracking the same event but with
            different filters and aggregation
        filters:
          type: array
          description: >-
            Filters define the criteria for the meter to be applied on the
            events before aggregation

            It also defines the possible values on which later the charges will
            be applied
          items:
            $ref: '#/components/schemas/meter.Filter'
        id:
          type: string
          description: ID is the unique identifier for the meter
        name:
          type: string
          description: Name is the display name of the meter
        reset_usage:
          $ref: '#/components/schemas/types.ResetUsage'
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    Plan:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        description:
          type: string
        display_order:
          type: integer
        environment_id:
          type: string
        id:
          type: string
        lookup_key:
          type: string
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        name:
          type: string
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    UsageAnalyticPoint:
      type: object
      properties:
        computed_commitment_utilized_amount:
          type: string
          description: Commitment breakdown (only populated for windowed commitments)
        computed_overage_amount:
          type: string
        computed_true_up_amount:
          type: string
        cost:
          type: string
        event_count:
          type: integer
          description: Number of events in this time window
        timestamp:
          type: string
        usage:
          type: string
    PriceResponse:
      type: object
      properties:
        addon:
          $ref: '#/components/schemas/AddonResponse'
        amount:
          type: string
          description: |-
            Amount stored in main currency units (e.g., dollars, not cents)
            For USD: 12.50 means $12.50
        billing_cadence:
          $ref: '#/components/schemas/types.BillingCadence'
        billing_model:
          $ref: '#/components/schemas/types.BillingModel'
        billing_period:
          $ref: '#/components/schemas/types.BillingPeriod'
        billing_period_count:
          type: integer
          description: BillingPeriodCount is the count of the billing period ex 1, 3, 6, 12
        conversion_rate:
          type: string
          description: >-
            ConversionRate is the conversion rate of the price unit to the fiat
            currency
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        currency:
          type: string
          description: Currency 3 digit ISO currency code in lowercase ex usd, eur, gbp
        description:
          type: string
          description: Description of the price
        display_amount:
          type: string
          description: |-
            DisplayAmount is the formatted amount with currency symbol
            For USD: $12.50
        display_name:
          type: string
          description: DisplayName is the name of the price
        display_price_unit_amount:
          type: string
          description: DisplayPriceUnitAmount is the formatted amount of the price unit
        end_date:
          type: string
          description: EndDate is the end date of the price
          format: date-time
        entity_id:
          type: string
          description: EntityID holds the value of the "entity_id" field.
        entity_type:
          $ref: '#/components/schemas/types.PriceEntityType'
        environment_id:
          type: string
          description: EnvironmentID is the environment identifier for the price
        group:
          $ref: '#/components/schemas/GroupResponse'
        group_id:
          type: string
          description: GroupID references the group this price belongs to
        id:
          type: string
          description: ID uuid identifier for the price
        invoice_cadence:
          $ref: '#/components/schemas/types.InvoiceCadence'
        lookup_key:
          type: string
          description: LookupKey used for looking up the price in the database
        metadata:
          $ref: '#/components/schemas/price.JSONBMetadata'
        meter:
          $ref: '#/components/schemas/MeterResponse'
        meter_id:
          type: string
          description: MeterID is the id of the meter for usage based pricing
        min_quantity:
          type: string
          description: MinQuantity is the minimum quantity of the price
          nullable: true
        parent_price_id:
          type: string
          description: >-
            ParentPriceID references the root price (always set for price
            lineage tracking)
        plan:
          $ref: '#/components/schemas/PlanResponse'
        price_unit:
          type: string
          description: PriceUnit is the code of the price unit (e.g., 'btc', 'eth')
        price_unit_amount:
          type: string
          description: PriceUnitAmount is the amount of the price unit
        price_unit_id:
          type: string
          description: PriceUnitID is the id of the price unit (for CUSTOM type)
        price_unit_tiers:
          type: array
          description: >-
            PriceUnitTiers are the tiers for the price unit when BillingModel is
            TIERED
          items:
            $ref: '#/components/schemas/price.PriceTier'
        price_unit_type:
          $ref: '#/components/schemas/types.PriceUnitType'
        pricing_unit:
          $ref: '#/components/schemas/PriceUnitResponse'
        start_date:
          type: string
          description: StartDate is the start date of the price
          format: date-time
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        tier_mode:
          $ref: '#/components/schemas/types.BillingTier'
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/price.PriceTier'
        transform_quantity:
          $ref: '#/components/schemas/price.JSONBTransformQuantity'
        trial_period_days:
          type: integer
          description: >-
            TrialPeriodDays is the number of days for the trial period

            Note: This is only applicable for recurring prices
            (BILLING_CADENCE_RECURRING)
        type:
          $ref: '#/components/schemas/types.PriceType'
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.ReportingUnit:
      type: object
      properties:
        conversion_rate:
          type: number
          description: >-
            Multiplier: reporting_unit_value = unit_value * conversion_rate;
            must be > 0
        unit_plural:
          type: string
          description: Display unit label, plural (e.g. "seconds")
        unit_singular:
          type: string
          description: Display unit label, singular (e.g. "second")
      x-speakeasy-name-override: ReportingUnit
    subscription.SubscriptionLineItem:
      type: object
      properties:
        addon_association_id:
          type: string
        billing_period:
          $ref: '#/components/schemas/types.BillingPeriod'
        billing_period_count:
          type: integer
          description: from price at create; default 1
        commitment_amount:
          type: string
          description: Commitment fields
        commitment_duration:
          $ref: '#/components/schemas/types.BillingPeriod'
        commitment_overage_factor:
          type: string
        commitment_quantity:
          type: string
        commitment_true_up_enabled:
          type: boolean
        commitment_type:
          $ref: '#/components/schemas/types.CommitmentType'
        commitment_windowed:
          type: boolean
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        currency:
          type: string
        customer_id:
          type: string
        display_name:
          type: string
        end_date:
          type: string
          format: date-time
        entity_id:
          type: string
        entity_type:
          $ref: '#/components/schemas/types.SubscriptionLineItemEntityType'
        environment_id:
          type: string
        id:
          type: string
        invoice_cadence:
          $ref: '#/components/schemas/types.InvoiceCadence'
        metadata:
          type: object
          additionalProperties:
            type: string
        meter_display_name:
          type: string
        meter_id:
          type: string
        plan_display_name:
          type: string
        price:
          $ref: '#/components/schemas/price.Price'
        price_id:
          type: string
        price_type:
          $ref: '#/components/schemas/types.PriceType'
        price_unit:
          type: string
        price_unit_id:
          type: string
        quantity:
          type: string
        start_date:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/types.Status'
        subscription_id:
          type: string
        subscription_phase_id:
          type: string
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.Status:
      type: string
      enum:
        - published
        - deleted
        - archived
      x-enum-varnames:
        - StatusPublished
        - StatusDeleted
        - StatusArchived
      x-speakeasy-name-override: Status
    types.BillingPeriod:
      type: string
      enum:
        - MONTHLY
        - ANNUAL
        - WEEKLY
        - DAILY
        - QUARTERLY
        - HALF_YEARLY
        - ONETIME
      x-enum-varnames:
        - BILLING_PERIOD_MONTHLY
        - BILLING_PERIOD_ANNUAL
        - BILLING_PERIOD_WEEKLY
        - BILLING_PERIOD_DAILY
        - BILLING_PERIOD_QUARTER
        - BILLING_PERIOD_HALF_YEAR
        - BILLING_PERIOD_ONETIME
      x-speakeasy-name-override: BillingPeriod
    types.CommitmentType:
      type: string
      enum:
        - amount
        - quantity
      x-enum-varnames:
        - COMMITMENT_TYPE_AMOUNT
        - COMMITMENT_TYPE_QUANTITY
      x-speakeasy-name-override: CommitmentType
    types.AlertSettings:
      type: object
      properties:
        alert_enabled:
          type: boolean
        critical:
          $ref: '#/components/schemas/types.AlertThreshold'
        info:
          $ref: '#/components/schemas/types.AlertThreshold'
        warning:
          $ref: '#/components/schemas/types.AlertThreshold'
      x-speakeasy-name-override: AlertSettings
    types.Metadata:
      type: object
      additionalProperties:
        type: string
      x-speakeasy-name-override: Metadata
    types.FeatureType:
      type: string
      enum:
        - metered
        - boolean
        - static
      x-enum-varnames:
        - FeatureTypeMetered
        - FeatureTypeBoolean
        - FeatureTypeStatic
      x-speakeasy-name-override: FeatureType
    types.GroupEntityType:
      type: string
      enum:
        - price
        - feature
      x-enum-varnames:
        - GroupEntityTypePrice
        - GroupEntityTypeFeature
      x-speakeasy-name-override: GroupEntityType
    meter.Aggregation:
      type: object
      properties:
        bucket_size:
          $ref: '#/components/schemas/types.WindowSize'
        expression:
          type: string
          description: >-
            Expression is an optional CEL expression to compute per-event
            quantity from event.properties.

            When set, it replaces Field-based extraction. Property names are
            used directly (e.g., token * duration * pixel).
        field:
          type: string
          description: >-
            Field is the key in $event.properties on which the aggregation is to
            be applied

            For ex if the aggregation type is sum for API usage, the field could
            be "duration_ms"

            Ignored when Expression is set.
        group_by:
          type: string
          description: >-
            GroupBy is the property name in event.properties to group by before
            aggregating.

            Currently only supported for MAX aggregation with bucket_size.

            When set, aggregation is applied per unique value of this property
            within each bucket,

            then the per-group results are summed to produce the bucket total.
        multiplier:
          type: string
          description: >-
            Multiplier is the multiplier for the aggregation

            For ex if the aggregation type is sum_with_multiplier for API usage,
            the multiplier could be 1000

            to scale up by a factor of 1000. If not provided, it will be null.
        type:
          $ref: '#/components/schemas/types.AggregationType'
    meter.Filter:
      type: object
      properties:
        key:
          type: string
          description: >-
            Key is the key for the filter from $event.properties

            Currently we support only first level keys in the properties and not
            nested keys
        values:
          type: array
          description: >-
            Values are the possible values for the filter to be considered for
            the meter

            For ex "model_name" could have values "o1-mini", "gpt-4o" etc
          items:
            type: string
    types.ResetUsage:
      type: string
      enum:
        - BILLING_PERIOD
        - NEVER
      x-enum-varnames:
        - ResetUsageBillingPeriod
        - ResetUsageNever
      x-speakeasy-name-override: ResetUsage
    AddonResponse:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        description:
          type: string
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/EntitlementResponse'
        environment_id:
          type: string
        id:
          type: string
        lookup_key:
          type: string
        metadata:
          type: object
          additionalProperties: true
        name:
          type: string
        prices:
          type: array
          description: Optional expanded fields
          items:
            $ref: '#/components/schemas/PriceResponse'
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.BillingCadence:
      type: string
      enum:
        - RECURRING
      x-enum-varnames:
        - BILLING_CADENCE_RECURRING
      x-speakeasy-name-override: BillingCadence
    types.BillingModel:
      type: string
      enum:
        - FLAT_FEE
        - PACKAGE
        - TIERED
      x-enum-varnames:
        - BILLING_MODEL_FLAT_FEE
        - BILLING_MODEL_PACKAGE
        - BILLING_MODEL_TIERED
      x-speakeasy-name-override: BillingModel
    types.PriceEntityType:
      type: string
      enum:
        - PLAN
        - SUBSCRIPTION
        - ADDON
        - PRICE
        - COSTSHEET
      x-enum-varnames:
        - PRICE_ENTITY_TYPE_PLAN
        - PRICE_ENTITY_TYPE_SUBSCRIPTION
        - PRICE_ENTITY_TYPE_ADDON
        - PRICE_ENTITY_TYPE_PRICE
        - PRICE_ENTITY_TYPE_COSTSHEET
      x-speakeasy-name-override: PriceEntityType
    GroupResponse:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        entity_ids:
          type: array
          items:
            type: string
        entity_type:
          type: string
        id:
          type: string
        lookup_key:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        name:
          type: string
        status:
          type: string
        updated_at:
          type: string
          format: date-time
    types.InvoiceCadence:
      type: string
      enum:
        - ARREAR
        - ADVANCE
      x-enum-varnames:
        - InvoiceCadenceArrear
        - InvoiceCadenceAdvance
      x-speakeasy-name-override: InvoiceCadence
    price.JSONBMetadata:
      type: object
      additionalProperties:
        type: string
    MeterResponse:
      type: object
      properties:
        aggregation:
          $ref: '#/components/schemas/meter.Aggregation'
        created_at:
          type: string
          example: '2024-03-20T15:04:05Z'
          format: date-time
        event_name:
          type: string
          example: api_request
        filters:
          type: array
          items:
            $ref: '#/components/schemas/meter.Filter'
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          example: API Usage Meter
        reset_usage:
          $ref: '#/components/schemas/types.ResetUsage'
        status:
          type: string
          example: published
        tenant_id:
          type: string
          example: tenant123
        updated_at:
          type: string
          example: '2024-03-20T15:04:05Z'
          format: date-time
    PlanResponse:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        credit_grants:
          type: array
          items:
            $ref: '#/components/schemas/CreditGrantResponse'
        description:
          type: string
        display_order:
          type: integer
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/EntitlementResponse'
        environment_id:
          type: string
        id:
          type: string
        lookup_key:
          type: string
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        name:
          type: string
        prices:
          type: array
          description: 'TODO: Add inline addons'
          items:
            $ref: '#/components/schemas/PriceResponse'
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    price.PriceTier:
      type: object
      properties:
        flat_amount:
          type: string
          description: >-
            flat_amount is the flat amount for the given tier (optional)

            Applied on top of unit_amount*quantity. Useful for cases like "2.7$
            + 5c"
        unit_amount:
          type: string
          description: unit_amount is the amount per unit for the given tier
        up_to:
          type: integer
          description: >-
            up_to is the quantity up to which this tier applies. It is null for
            the last tier.

            IMPORTANT: Tier boundaries are INCLUSIVE.

            - If up_to is 1000, then quantity less than or equal to 1000 belongs
            to this tier

            - This behavior is consistent across both VOLUME and SLAB tier modes
    types.PriceUnitType:
      type: string
      enum:
        - FIAT
        - CUSTOM
      x-enum-varnames:
        - PRICE_UNIT_TYPE_FIAT
        - PRICE_UNIT_TYPE_CUSTOM
      x-speakeasy-name-override: PriceUnitType
    PriceUnitResponse:
      type: object
      properties:
        base_currency:
          type: string
        code:
          type: string
        conversion_rate:
          type: string
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        environment_id:
          type: string
        id:
          type: string
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        name:
          type: string
        status:
          $ref: '#/components/schemas/types.Status'
        symbol:
          type: string
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.BillingTier:
      type: string
      enum:
        - VOLUME
        - SLAB
      x-enum-varnames:
        - BILLING_TIER_VOLUME
        - BILLING_TIER_SLAB
      x-speakeasy-name-override: BillingTier
    price.JSONBTransformQuantity:
      type: object
      properties:
        divide_by:
          type: integer
          description: Divide quantity by this number
        round:
          $ref: '#/components/schemas/types.RoundType'
    types.PriceType:
      type: string
      enum:
        - USAGE
        - FIXED
      x-enum-varnames:
        - PRICE_TYPE_USAGE
        - PRICE_TYPE_FIXED
      x-speakeasy-name-override: PriceType
    types.SubscriptionLineItemEntityType:
      type: string
      enum:
        - plan
        - addon
        - subscription
      x-enum-varnames:
        - SubscriptionLineItemEntityTypePlan
        - SubscriptionLineItemEntityTypeAddon
        - SubscriptionLineItemEntityTypeSubscription
      x-speakeasy-name-override: SubscriptionLineItemEntityType
    price.Price:
      type: object
      properties:
        amount:
          type: string
          description: |-
            Amount stored in main currency units (e.g., dollars, not cents)
            For USD: 12.50 means $12.50
        billing_cadence:
          $ref: '#/components/schemas/types.BillingCadence'
        billing_model:
          $ref: '#/components/schemas/types.BillingModel'
        billing_period:
          $ref: '#/components/schemas/types.BillingPeriod'
        billing_period_count:
          type: integer
          description: BillingPeriodCount is the count of the billing period ex 1, 3, 6, 12
        conversion_rate:
          type: string
          description: >-
            ConversionRate is the conversion rate of the price unit to the fiat
            currency
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        currency:
          type: string
          description: Currency 3 digit ISO currency code in lowercase ex usd, eur, gbp
        description:
          type: string
          description: Description of the price
        display_amount:
          type: string
          description: |-
            DisplayAmount is the formatted amount with currency symbol
            For USD: $12.50
        display_name:
          type: string
          description: DisplayName is the name of the price
        display_price_unit_amount:
          type: string
          description: DisplayPriceUnitAmount is the formatted amount of the price unit
        end_date:
          type: string
          description: EndDate is the end date of the price
          format: date-time
        entity_id:
          type: string
          description: EntityID holds the value of the "entity_id" field.
        entity_type:
          $ref: '#/components/schemas/types.PriceEntityType'
        environment_id:
          type: string
          description: EnvironmentID is the environment identifier for the price
        group_id:
          type: string
          description: GroupID references the group this price belongs to
        id:
          type: string
          description: ID uuid identifier for the price
        invoice_cadence:
          $ref: '#/components/schemas/types.InvoiceCadence'
        lookup_key:
          type: string
          description: LookupKey used for looking up the price in the database
        metadata:
          $ref: '#/components/schemas/price.JSONBMetadata'
        meter_id:
          type: string
          description: MeterID is the id of the meter for usage based pricing
        min_quantity:
          type: string
          description: MinQuantity is the minimum quantity of the price
          nullable: true
        parent_price_id:
          type: string
          description: >-
            ParentPriceID references the root price (always set for price
            lineage tracking)
        price_unit:
          type: string
          description: PriceUnit is the code of the price unit (e.g., 'btc', 'eth')
        price_unit_amount:
          type: string
          description: PriceUnitAmount is the amount of the price unit
        price_unit_id:
          type: string
          description: PriceUnitID is the id of the price unit (for CUSTOM type)
        price_unit_tiers:
          type: array
          description: >-
            PriceUnitTiers are the tiers for the price unit when BillingModel is
            TIERED
          items:
            $ref: '#/components/schemas/price.PriceTier'
        price_unit_type:
          $ref: '#/components/schemas/types.PriceUnitType'
        start_date:
          type: string
          description: StartDate is the start date of the price
          format: date-time
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        tier_mode:
          $ref: '#/components/schemas/types.BillingTier'
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/price.PriceTier'
        transform_quantity:
          $ref: '#/components/schemas/price.JSONBTransformQuantity'
        trial_period_days:
          type: integer
          description: >-
            TrialPeriodDays is the number of days for the trial period

            Note: This is only applicable for recurring prices
            (BILLING_CADENCE_RECURRING)
        type:
          $ref: '#/components/schemas/types.PriceType'
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.AlertThreshold:
      type: object
      properties:
        condition:
          $ref: '#/components/schemas/types.AlertCondition'
        threshold:
          type: number
      x-speakeasy-name-override: AlertThreshold
    EntitlementResponse:
      type: object
      properties:
        addon:
          $ref: '#/components/schemas/AddonResponse'
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        display_order:
          type: integer
        end_date:
          type: string
          format: date-time
        entity_id:
          type: string
        entity_type:
          $ref: '#/components/schemas/types.EntitlementEntityType'
        environment_id:
          type: string
        feature:
          $ref: '#/components/schemas/FeatureResponse'
        feature_id:
          type: string
        feature_type:
          $ref: '#/components/schemas/types.FeatureType'
        id:
          type: string
        is_enabled:
          type: boolean
        is_soft_limit:
          type: boolean
        parent_entitlement_id:
          type: string
        plan:
          $ref: '#/components/schemas/PlanResponse'
        plan_id:
          type: string
          description: 'TODO: Remove this once we have a proper entitlement entity type'
        start_date:
          type: string
          format: date-time
        static_value:
          type: string
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
        usage_limit:
          type: integer
        usage_reset_period:
          $ref: '#/components/schemas/types.EntitlementUsageResetPeriod'
    CreditGrantResponse:
      type: object
      properties:
        cadence:
          $ref: '#/components/schemas/types.CreditGrantCadence'
        conversion_rate:
          type: string
          description: |-
            amount in the currency =  number of credits * conversion_rate
            ex if conversion_rate is 1, then 1 USD = 1 credit
            ex if conversion_rate is 2, then 1 USD = 0.5 credits
            ex if conversion_rate is 0.5, then 1 USD = 2 credits
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        credit_grant_anchor:
          type: string
          format: date-time
        credits:
          type: string
        end_date:
          type: string
          format: date-time
        environment_id:
          type: string
        expiration_duration:
          type: integer
        expiration_duration_unit:
          $ref: '#/components/schemas/types.CreditGrantExpiryDurationUnit'
        expiration_type:
          $ref: '#/components/schemas/types.CreditGrantExpiryType'
        id:
          type: string
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        name:
          type: string
        period:
          $ref: '#/components/schemas/types.CreditGrantPeriod'
        period_count:
          type: integer
        plan_id:
          type: string
        priority:
          type: integer
        scope:
          $ref: '#/components/schemas/types.CreditGrantScope'
        start_date:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/types.Status'
        subscription_id:
          type: string
        tenant_id:
          type: string
        topup_conversion_rate:
          type: string
          description: >-
            topup_conversion_rate is the conversion rate for the topup to the
            currency

            ex if topup_conversion_rate is 1, then 1 USD = 1 credit

            ex if topup_conversion_rate is 2, then 1 USD = 0.5 credits

            ex if topup_conversion_rate is 0.5, then 1 USD = 2 credits
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.RoundType:
      type: string
      enum:
        - up
        - down
      x-enum-varnames:
        - ROUND_UP
        - ROUND_DOWN
      x-speakeasy-name-override: RoundType
    types.AlertCondition:
      type: string
      enum:
        - above
        - below
      x-enum-varnames:
        - AlertConditionAbove
        - AlertConditionBelow
      x-speakeasy-name-override: AlertCondition
    types.EntitlementEntityType:
      type: string
      enum:
        - PLAN
        - SUBSCRIPTION
        - ADDON
      x-enum-varnames:
        - ENTITLEMENT_ENTITY_TYPE_PLAN
        - ENTITLEMENT_ENTITY_TYPE_SUBSCRIPTION
        - ENTITLEMENT_ENTITY_TYPE_ADDON
      x-speakeasy-name-override: EntitlementEntityType
    FeatureResponse:
      type: object
      properties:
        alert_settings:
          $ref: '#/components/schemas/types.AlertSettings'
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        description:
          type: string
        environment_id:
          type: string
        group:
          $ref: '#/components/schemas/GroupResponse'
        group_id:
          type: string
        id:
          type: string
        lookup_key:
          type: string
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        meter:
          $ref: '#/components/schemas/MeterResponse'
        meter_id:
          type: string
        name:
          type: string
        reporting_unit:
          $ref: '#/components/schemas/types.ReportingUnit'
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        type:
          $ref: '#/components/schemas/types.FeatureType'
        unit_plural:
          type: string
        unit_singular:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.EntitlementUsageResetPeriod:
      type: string
      enum:
        - MONTHLY
        - ANNUAL
        - WEEKLY
        - DAILY
        - QUARTERLY
        - HALF_YEARLY
        - NEVER
      x-enum-varnames:
        - ENTITLEMENT_USAGE_RESET_PERIOD_MONTHLY
        - ENTITLEMENT_USAGE_RESET_PERIOD_ANNUAL
        - ENTITLEMENT_USAGE_RESET_PERIOD_WEEKLY
        - ENTITLEMENT_USAGE_RESET_PERIOD_DAILY
        - ENTITLEMENT_USAGE_RESET_PERIOD_QUARTER
        - ENTITLEMENT_USAGE_RESET_PERIOD_HALF_YEAR
        - ENTITLEMENT_USAGE_RESET_PERIOD_NEVER
      x-speakeasy-name-override: EntitlementUsageResetPeriod
    types.CreditGrantCadence:
      type: string
      enum:
        - ONETIME
        - RECURRING
      x-enum-varnames:
        - CreditGrantCadenceOneTime
        - CreditGrantCadenceRecurring
      x-speakeasy-name-override: CreditGrantCadence
    types.CreditGrantExpiryDurationUnit:
      type: string
      enum:
        - DAY
        - WEEK
        - MONTH
        - YEAR
      x-enum-varnames:
        - CreditGrantExpiryDurationUnitDays
        - CreditGrantExpiryDurationUnitWeeks
        - CreditGrantExpiryDurationUnitMonths
        - CreditGrantExpiryDurationUnitYears
      x-speakeasy-name-override: CreditGrantExpiryDurationUnit
    types.CreditGrantExpiryType:
      type: string
      enum:
        - NEVER
        - DURATION
        - BILLING_CYCLE
      x-enum-varnames:
        - CreditGrantExpiryTypeNever
        - CreditGrantExpiryTypeDuration
        - CreditGrantExpiryTypeBillingCycle
      x-speakeasy-name-override: CreditGrantExpiryType
    types.CreditGrantPeriod:
      type: string
      enum:
        - DAILY
        - WEEKLY
        - MONTHLY
        - ANNUAL
        - QUARTERLY
        - HALF_YEARLY
      x-enum-varnames:
        - CREDIT_GRANT_PERIOD_DAILY
        - CREDIT_GRANT_PERIOD_WEEKLY
        - CREDIT_GRANT_PERIOD_MONTHLY
        - CREDIT_GRANT_PERIOD_ANNUAL
        - CREDIT_GRANT_PERIOD_QUARTER
        - CREDIT_GRANT_PERIOD_HALF_YEARLY
      x-speakeasy-name-override: CreditGrantPeriod
    types.CreditGrantScope:
      type: string
      enum:
        - PLAN
        - SUBSCRIPTION
      x-enum-varnames:
        - CreditGrantScopePlan
        - CreditGrantScopeSubscription
      x-speakeasy-name-override: CreditGrantScope
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Enter your API key in the format *x-api-key &lt;api-key&gt;**
      name: x-api-key
      in: header

````