> ## 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 combined revenue and cost analytics (V2)

> Use when you need the same revenue/cost/ROI analytics but computed from the costsheet usage-tracking pipeline (e.g. for consistency with usage-based cost data).



## OpenAPI

````yaml /api-reference/openapi.json post /costs/analytics-v2
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:
  /costs/analytics-v2:
    post:
      tags:
        - Costs
      summary: Get combined revenue and cost analytics (V2)
      description: >-
        Use when you need the same revenue/cost/ROI analytics but computed from
        the costsheet usage-tracking pipeline (e.g. for consistency with
        usage-based cost data).
      operationId: getDetailedCostAnalyticsV2
      requestBody:
        description: >-
          Combined analytics request (start_time/end_time optional - defaults to
          last 7 days)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCostAnalyticsRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDetailedCostAnalyticsResponse'
        '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:
    GetCostAnalyticsRequest:
      type: object
      properties:
        end_time:
          type: string
          format: date-time
        expand:
          type: array
          description: Expand options - specify which entities to expand
          items:
            type: string
        external_customer_id:
          type: string
          description: Optional - for specific customer
        feature_ids:
          type: array
          description: Additional filters
          items:
            type: string
        limit:
          type: integer
          description: Pagination
        offset:
          type: integer
        start_time:
          type: string
          description: >-
            Time range fields (optional - defaults to last 7 days if not
            provided)
          format: date-time
    GetDetailedCostAnalyticsResponse:
      type: object
      properties:
        cost_analytics:
          type: array
          description: Cost analytics array (flattened from nested structure)
          items:
            $ref: '#/components/schemas/CostAnalyticItem'
        currency:
          type: string
        end_time:
          type: string
          format: date-time
        margin:
          type: string
          description: Revenue - Cost
        margin_percent:
          type: string
          description: (Margin / Revenue) * 100
        roi:
          type: string
          description: (Revenue - Cost) / Cost
        roi_percent:
          type: string
          description: ROI * 100
        start_time:
          type: string
          format: date-time
        total_cost:
          type: string
        total_revenue:
          type: string
          description: Derived metrics
    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
    CostAnalyticItem:
      type: object
      properties:
        cost_by_period:
          type: array
          description: Breakdown
          items:
            $ref: '#/components/schemas/CostPoint'
        costsheet_id:
          type: string
        currency:
          type: string
          description: Metadata
        customer_id:
          type: string
        external_customer_id:
          type: string
        meter:
          $ref: '#/components/schemas/meter.Meter'
        meter_id:
          type: string
        meter_name:
          type: string
        price:
          $ref: '#/components/schemas/price.Price'
        price_id:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
        source:
          type: string
        total_cost:
          type: string
          description: Aggregated metrics
        total_events:
          type: integer
        total_quantity:
          type: string
    CostPoint:
      type: object
      properties:
        cost:
          type: string
        event_count:
          type: integer
        quantity:
          type: string
        timestamp:
          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
    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
    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
    types.Status:
      type: string
      enum:
        - published
        - deleted
        - archived
      x-enum-varnames:
        - StatusPublished
        - StatusDeleted
        - StatusArchived
      x-speakeasy-name-override: Status
    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.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.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
    types.InvoiceCadence:
      type: string
      enum:
        - ARREAR
        - ADVANCE
      x-enum-varnames:
        - InvoiceCadenceArrear
        - InvoiceCadenceAdvance
      x-speakeasy-name-override: InvoiceCadence
    price.JSONBMetadata:
      type: object
      additionalProperties:
        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
    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.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
    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.RoundType:
      type: string
      enum:
        - up
        - down
      x-enum-varnames:
        - ROUND_UP
        - ROUND_DOWN
      x-speakeasy-name-override: RoundType
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Enter your API key in the format *x-api-key <api-key>**
      name: x-api-key
      in: header

````