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

# Get Revenue Metrics

> Closed-won bookings and win rate from the CRM deals Octave has synced. This is not ARR and not billing revenue: the sync covers only part of the history (see coverage.earliestClosedDate), churn usually leaves no CRM deal, and amounts are contract values. Computed by code, the same on every call over the same data: use it instead of adding up deal/list rows yourself. For a close-date window (closeDateFrom / closeDateTo, whole days; omit for all synced history) it returns closed-won bookings (closedWonAmount), win rate (won / (won + lost)), average and median deal size, and median sales cycle in days (creation to close), all in the workspace's home currency (amountHome). Which deals count is the workspace's revenue rule: which pipelines count and which deal types are left out. The rule is the workspace's setting (the result echoes it under rule); the request cannot override it. A multi-year deal counts at its full amount. Never present these figures as ARR, and never call a window without a start all-time: it begins where the sync does. Pass groupBy to break the window down by segment (the account's segment), use_case, persona, offering (a product, service or solution), core_feature (what the deal's conversations raised; a deal falls under every one it raised, so those rows overlap and do not add up to the totals), tag (needs tagGroupId, an oId from tag-group/list, and nothing else takes it; tag rows overlap too), or owner (the CRM deal owner). Deals with no group are in rows with key null, told apart by the row's unassigned reason: "not_raised" means the deal has recorded calls or emails but none raised one, while "no_conversations" means Octave has no recorded calls or emails for the deal at all, so the row says nothing about what the deal was about; segment, owner and tag use no_segment, no_owner and no_tag. Every number carries the won deal ids behind it. Read coverage and warnings before quoting a figure: windowStartsBeforeSync means older deals are missing from the totals, coverage.dealsWithoutConversations counts closed deals with no recorded calls or emails, and warnings name rule values that matched nothing. Deals outside Octave's sync are not counted. REST twin of the get_revenue_metrics MCP tool; takes the same body.



## OpenAPI

````yaml post /api/v2/deal/revenue-metrics
openapi: 3.0.0
info:
  version: 7.3.0
  title: Octave API
  description: API for Octave workspace management and AI-powered content generation
servers:
  - url: https://app.octavehq.com
security:
  - ApiKeyAuth: []
paths:
  /api/v2/deal/revenue-metrics:
    post:
      tags:
        - Deals
      summary: Get Revenue Metrics
      description: >-
        Closed-won bookings and win rate from the CRM deals Octave has synced.
        This is not ARR and not billing revenue: the sync covers only part of
        the history (see coverage.earliestClosedDate), churn usually leaves no
        CRM deal, and amounts are contract values. Computed by code, the same on
        every call over the same data: use it instead of adding up deal/list
        rows yourself. For a close-date window (closeDateFrom / closeDateTo,
        whole days; omit for all synced history) it returns closed-won bookings
        (closedWonAmount), win rate (won / (won + lost)), average and median
        deal size, and median sales cycle in days (creation to close), all in
        the workspace's home currency (amountHome). Which deals count is the
        workspace's revenue rule: which pipelines count and which deal types are
        left out. The rule is the workspace's setting (the result echoes it
        under rule); the request cannot override it. A multi-year deal counts at
        its full amount. Never present these figures as ARR, and never call a
        window without a start all-time: it begins where the sync does. Pass
        groupBy to break the window down by segment (the account's segment),
        use_case, persona, offering (a product, service or solution),
        core_feature (what the deal's conversations raised; a deal falls under
        every one it raised, so those rows overlap and do not add up to the
        totals), tag (needs tagGroupId, an oId from tag-group/list, and nothing
        else takes it; tag rows overlap too), or owner (the CRM deal owner).
        Deals with no group are in rows with key null, told apart by the row's
        unassigned reason: "not_raised" means the deal has recorded calls or
        emails but none raised one, while "no_conversations" means Octave has no
        recorded calls or emails for the deal at all, so the row says nothing
        about what the deal was about; segment, owner and tag use no_segment,
        no_owner and no_tag. Every number carries the won deal ids behind it.
        Read coverage and warnings before quoting a figure:
        windowStartsBeforeSync means older deals are missing from the totals,
        coverage.dealsWithoutConversations counts closed deals with no recorded
        calls or emails, and warnings name rule values that matched nothing.
        Deals outside Octave's sync are not counted. REST twin of the
        get_revenue_metrics MCP tool; takes the same body.
      operationId: getRevenueMetrics
      requestBody:
        description: Close-date window and optional breakdown
        content:
          application/json:
            schema:
              type: object
              properties:
                closeDateFrom:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
                  description: >-
                    Start of the window: only deals that closed on or after this
                    day (YYYY-MM-DD, UTC). Omit for all time.
                closeDateTo:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
                  description: >-
                    End of the window: only deals that closed on or before this
                    day (YYYY-MM-DD, UTC), the whole day included. Defaults to
                    asOf.
                asOf:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
                  description: >-
                    The day the numbers are read as of (YYYY-MM-DD, UTC), the
                    whole day included. Defaults to today. Deals closed on or
                    before it count, and a deal dated after it has not closed
                    yet.
                groupBy:
                  type: string
                  enum:
                    - segment
                    - use_case
                    - persona
                    - owner
                    - offering
                    - core_feature
                    - tag
                  description: >-
                    Break the window's numbers down by segment (the account's
                    segment), use_case, persona, offering (product, service or
                    solution) or core_feature (what the deal's conversations
                    raised; a deal can fall under several, so rows overlap), tag
                    (the tags in the tagGroupId group carried by the library
                    entities the deal is linked to; a deal falls under each tag
                    once, so rows overlap), or owner (the CRM deal owner). Omit
                    for totals only.
                tagGroupId:
                  type: string
                  minLength: 1
                  description: >-
                    Only with groupBy "tag": the oId of the tag group to break
                    down by (list_tag_groups returns them). A tag group applies
                    to one kind of library entity (segment, use case, persona,
                    product, service, solution or core feature); a deal falls
                    under a tag when the entity of that kind it is linked to
                    carries the tag, and in the "No tag in group" row when none
                    does (or "No calls or emails" when it has no recorded
                    conversations).
      responses:
        '200':
          description: Revenue metrics for the window
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
                  summary:
                    type: string
                    description: >-
                      One-line reading of this result for a person. The fields
                      beside it are the data; read them, not this, for figures.
                  asOf:
                    type: string
                    description: The day the numbers are read as of.
                  window:
                    type: object
                    properties:
                      from:
                        type: string
                        nullable: true
                        description: Null = all time.
                      to:
                        type: string
                    required:
                      - from
                      - to
                  rule:
                    type: object
                    properties:
                      pipelines:
                        type: array
                        items:
                          type: string
                          minLength: 1
                          maxLength: 200
                        maxItems: 50
                        default: []
                      excludedDealTypes:
                        type: array
                        items:
                          type: string
                          minLength: 1
                          maxLength: 200
                        maxItems: 50
                        default: []
                      isSet:
                        type: boolean
                        description: >-
                          False when the workspace never set a rule: the default
                          applies.
                    required:
                      - isSet
                  homeCurrency:
                    type: string
                    nullable: true
                  totals:
                    type: object
                    properties:
                      closedWonAmount:
                        type: number
                        description: >-
                          Sum of amountHome over the won deals, in the home
                          currency.
                      wonDeals:
                        type: integer
                      lostDeals:
                        type: integer
                      winRate:
                        type: number
                        nullable: true
                        description: won / (won + lost), 0..1; null with no closed deals.
                      averageDealSize:
                        type: number
                        nullable: true
                        description: Mean amountHome of the won deals that carry an amount.
                      medianDealSize:
                        type: number
                        nullable: true
                        description: >-
                          Median amountHome of the won deals that carry an
                          amount, whole currency units.
                      medianCycleDays:
                        type: number
                        nullable: true
                        description: >-
                          Median days from creation to close over all closed
                          deals, won and lost, as the win/loss lab reads it.
                      medianWonCycleDays:
                        type: number
                        nullable: true
                        description: >-
                          Median days from creation to close over the won deals
                          only.
                      wonDealOIds:
                        type: array
                        items:
                          type: string
                        description: The won deals behind closedWonAmount, ascending.
                    required:
                      - closedWonAmount
                      - wonDeals
                      - lostDeals
                      - winRate
                      - averageDealSize
                      - medianDealSize
                      - medianCycleDays
                      - medianWonCycleDays
                      - wonDealOIds
                  groups:
                    type: object
                    nullable: true
                    properties:
                      groupBy:
                        type: string
                        enum:
                          - segment
                          - use_case
                          - persona
                          - owner
                          - offering
                          - core_feature
                          - tag
                      guide:
                        type: string
                        description: >-
                          How to read these rows: whether they may be added up,
                          and what the rows with key null are. Read it before
                          using the rows.
                      overlapping:
                        type: boolean
                        description: >-
                          True when one deal can fall under several rows, so
                          rows do not add up to the totals.
                      tagGroup:
                        type: object
                        nullable: true
                        properties:
                          oId:
                            type: string
                          name:
                            type: string
                        required:
                          - oId
                          - name
                        description: >-
                          The tag group the rows are tags of; only with groupBy
                          "tag".
                      rows:
                        type: array
                        items:
                          type: object
                          properties:
                            closedWonAmount:
                              type: number
                              description: >-
                                Sum of amountHome over the won deals, in the
                                home currency.
                            wonDeals:
                              type: integer
                            lostDeals:
                              type: integer
                            winRate:
                              type: number
                              nullable: true
                              description: >-
                                won / (won + lost), 0..1; null with no closed
                                deals.
                            averageDealSize:
                              type: number
                              nullable: true
                              description: >-
                                Mean amountHome of the won deals that carry an
                                amount.
                            medianDealSize:
                              type: number
                              nullable: true
                              description: >-
                                Median amountHome of the won deals that carry an
                                amount, whole currency units.
                            medianCycleDays:
                              type: number
                              nullable: true
                              description: >-
                                Median days from creation to close over all
                                closed deals, won and lost, as the win/loss lab
                                reads it.
                            medianWonCycleDays:
                              type: number
                              nullable: true
                              description: >-
                                Median days from creation to close over the won
                                deals only.
                            wonDealOIds:
                              type: array
                              items:
                                type: string
                              description: The won deals behind closedWonAmount, ascending.
                            key:
                              type: string
                              nullable: true
                              description: >-
                                The library entity oId (segment, use case,
                                persona, offering, core feature), the tag oId
                                (tag), or the owner's email; null for the rows
                                of deals with no group (see unassigned).
                            label:
                              type: string
                            unassigned:
                              type: string
                              nullable: true
                              enum:
                                - not_raised
                                - no_conversations
                                - no_segment
                                - no_owner
                                - no_tag
                                - null
                              description: >-
                                Null for a real group. Otherwise why these deals
                                have none: not_raised (they have recorded calls
                                or emails but none raised one), no_conversations
                                (no recorded calls or emails, so the breakdown
                                cannot place them; says nothing about the deal),
                                no_segment (the account has no segment),
                                no_owner (no deal owner), no_tag (none of the
                                entities the deal is linked to carries a tag in
                                the group).
                            explanation:
                              type: string
                              nullable: true
                              description: >-
                                Null for a real group. For a row of unplaced
                                deals, what it means in a sentence, to quote
                                rather than guess.
                          required:
                            - closedWonAmount
                            - wonDeals
                            - lostDeals
                            - winRate
                            - averageDealSize
                            - medianDealSize
                            - medianCycleDays
                            - medianWonCycleDays
                            - wonDealOIds
                            - key
                            - label
                            - unassigned
                            - explanation
                    required:
                      - groupBy
                      - guide
                      - overlapping
                      - rows
                  coverage:
                    type: object
                    properties:
                      closedDealsSynced:
                        type: integer
                        description: >-
                          Closed (won or lost) deals in Octave's synced copy,
                          before the rule or window.
                      closedDealsInWindow:
                        type: integer
                        description: Closed deals the totals are based on.
                      earliestClosedDate:
                        type: string
                        nullable: true
                        description: >-
                          Close day (YYYY-MM-DD) of the oldest closed deal
                          synced. Anything earlier is not in these numbers.
                      latestSyncedAt:
                        type: string
                        nullable: true
                        description: >-
                          When the newest synced deal was last read from the
                          CRM.
                      windowStartsBeforeSync:
                        type: boolean
                        description: >-
                          True when the window opens before the earliest synced
                          close date, or has no start: deals from before the
                          sync are missing from the totals.
                      wonDealsWithoutAmount:
                        type: integer
                        description: Won deals in the window with no amount; they add 0.
                      dealsWithoutConversations:
                        type: integer
                        description: >-
                          Closed deals in the window with no recorded calls or
                          emails (no processed conversation linked to them). The
                          use case, persona, offering and core feature
                          breakdowns cannot place them, so they fall in the
                          no_conversations row.
                    required:
                      - closedDealsSynced
                      - closedDealsInWindow
                      - earliestClosedDate
                      - latestSyncedAt
                      - windowStartsBeforeSync
                      - wonDealsWithoutAmount
                      - dealsWithoutConversations
                  warnings:
                    type: array
                    items:
                      type: string
                    description: >-
                      Reasons to read the numbers with care: a partial sync, a
                      rule value that matches nothing, a grouping that could not
                      be read.
                required:
                  - _metadata
                  - asOf
                  - window
                  - rule
                  - homeCurrency
                  - totals
                  - groups
                  - coverage
                  - warnings
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
                  message:
                    type: string
                required:
                  - _metadata
                  - message
      deprecated: false
components:
  schemas:
    Metadata:
      type: object
      properties:
        usage:
          type: number
          default: 0
          example: 0
          description: API usage
        requestId:
          type: string
          example: requestId
          description: Request ID
        message:
          type: string
          example: message
          description: Message
        timestamp:
          type: string
          example: '2021-01-01T00:00:00.000Z'
          description: Timestamp
      required:
        - requestId
        - timestamp
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.