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

# Get aggregated earnings summary

> Returns pre-aggregated earnings metrics for the authenticated creator, including all-time totals, month-over-month comparisons, source/type breakdowns, chart series, and averages.

<Info>
  **Required scope**

  * `read:insights` — Access analytics, metrics, and insights data for performance tracking.
</Info>


## OpenAPI

````yaml /openapi.json get /insights/earnings/summary
openapi: 3.1.0
info:
  title: Fanvue API
  version: '0.1'
servers: []
security: []
paths:
  /insights/earnings/summary:
    get:
      summary: Get aggregated earnings summary
      description: >-
        Returns pre-aggregated earnings metrics for the authenticated creator,
        including all-time totals, month-over-month comparisons, source/type
        breakdowns, chart series, and averages.
      operationId: getEarningsSummary
      parameters:
        - $ref: '#/components/parameters/ApiVersionHeader'
        - schema:
            type: string
            format: date-time
            description: >-
              Start date as ISO 8601 datetime string with optional timezone
              offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z).
          required: false
          description: >-
            Start date as ISO 8601 datetime string with optional timezone offset
            (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z).
          name: startDate
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              End date as ISO 8601 datetime string with optional timezone offset
              (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z).
              Non-inclusive - data before this date is included.
          required: false
          description: >-
            End date as ISO 8601 datetime string with optional timezone offset
            (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z).
            Non-inclusive - data before this date is included.
          name: endDate
          in: query
        - schema:
            type: string
            enum:
              - day
              - week
            default: day
            description: Aggregation granularity for the over-time chart
          required: false
          description: Aggregation granularity for the over-time chart
          name: granularity
          in: query
        - schema:
            type: string
            default: UTC
            description: >-
              IANA timezone used for period grouping and month boundaries (e.g.,
              Europe/London, America/New_York)
          required: false
          description: >-
            IANA timezone used for period grouping and month boundaries (e.g.,
            Europe/London, America/New_York)
          name: timezone
          in: query
      responses:
        '200':
          description: Aggregated earnings summary
          content:
            application/json:
              schema:
                type: object
                properties:
                  totals:
                    type: object
                    properties:
                      allTime:
                        type: object
                        properties:
                          gross:
                            type: number
                            description: Amount the fan paid, in USD cents
                          net:
                            type: number
                            description: Creator's cut after Fanvue fees, in USD cents
                        required:
                          - gross
                          - net
                      thisMonth:
                        type: object
                        properties:
                          gross:
                            type: number
                          net:
                            type: number
                          previousMonthGross:
                            type: number
                          previousMonthNet:
                            type: number
                          grossChangePercentage:
                            type:
                              - number
                              - 'null'
                          netChangePercentage:
                            type:
                              - number
                              - 'null'
                        required:
                          - gross
                          - net
                          - previousMonthGross
                          - previousMonthNet
                          - grossChangePercentage
                          - netChangePercentage
                    required:
                      - allTime
                      - thisMonth
                  breakdownBySource:
                    type: object
                    properties:
                      subs:
                        type: object
                        properties:
                          gross:
                            type: number
                            description: Amount the fan paid, in USD cents
                          net:
                            type: number
                            description: Creator's cut after Fanvue fees, in USD cents
                        required:
                          - gross
                          - net
                      messages:
                        type: object
                        properties:
                          gross:
                            type: number
                            description: Amount the fan paid, in USD cents
                          net:
                            type: number
                            description: Creator's cut after Fanvue fees, in USD cents
                        required:
                          - gross
                          - net
                      posts:
                        type: object
                        properties:
                          gross:
                            type: number
                            description: Amount the fan paid, in USD cents
                          net:
                            type: number
                            description: Creator's cut after Fanvue fees, in USD cents
                        required:
                          - gross
                          - net
                      tips:
                        type: object
                        properties:
                          gross:
                            type: number
                            description: Amount the fan paid, in USD cents
                          net:
                            type: number
                            description: Creator's cut after Fanvue fees, in USD cents
                        required:
                          - gross
                          - net
                      referrals:
                        type: object
                        properties:
                          gross:
                            type: number
                            description: Amount the fan paid, in USD cents
                          net:
                            type: number
                            description: Creator's cut after Fanvue fees, in USD cents
                        required:
                          - gross
                          - net
                      renewals:
                        type: object
                        properties:
                          gross:
                            type: number
                            description: Amount the fan paid, in USD cents
                          net:
                            type: number
                            description: Creator's cut after Fanvue fees, in USD cents
                        required:
                          - gross
                          - net
                      other:
                        type: object
                        properties:
                          gross:
                            type: number
                            description: Amount the fan paid, in USD cents
                          net:
                            type: number
                            description: Creator's cut after Fanvue fees, in USD cents
                        required:
                          - gross
                          - net
                    required:
                      - subs
                      - messages
                      - posts
                      - tips
                      - referrals
                      - renewals
                      - other
                  earningsByType:
                    type: object
                    properties:
                      renewals:
                        type: object
                        properties:
                          gross:
                            type: number
                            description: Amount the fan paid, in USD cents
                          net:
                            type: number
                            description: Creator's cut after Fanvue fees, in USD cents
                        required:
                          - gross
                          - net
                      messages:
                        type: object
                        properties:
                          gross:
                            type: number
                            description: Amount the fan paid, in USD cents
                          net:
                            type: number
                            description: Creator's cut after Fanvue fees, in USD cents
                        required:
                          - gross
                          - net
                      tips:
                        type: object
                        properties:
                          gross:
                            type: number
                            description: Amount the fan paid, in USD cents
                          net:
                            type: number
                            description: Creator's cut after Fanvue fees, in USD cents
                        required:
                          - gross
                          - net
                      subs:
                        type: object
                        properties:
                          gross:
                            type: number
                            description: Amount the fan paid, in USD cents
                          net:
                            type: number
                            description: Creator's cut after Fanvue fees, in USD cents
                        required:
                          - gross
                          - net
                    required:
                      - renewals
                      - messages
                      - tips
                      - subs
                  overTime:
                    type: array
                    items:
                      type: object
                      properties:
                        periodStart:
                          type: string
                          format: date-time
                          description: >-
                            Start of the aggregation bucket in ISO 8601 with
                            timezone offset
                        gross:
                          type: number
                          description: Amount fans paid in this bucket, in USD cents
                        net:
                          type: number
                          description: >-
                            Creator's cut after Fanvue fees in this bucket, in
                            USD cents
                      required:
                        - periodStart
                        - gross
                        - net
                  averageByDayOfWeek:
                    type: object
                    properties:
                      '1':
                        type: number
                      '2':
                        type: number
                      '3':
                        type: number
                      '4':
                        type: number
                      '5':
                        type: number
                      '6':
                        type: number
                      '7':
                        type: number
                    required:
                      - '1'
                      - '2'
                      - '3'
                      - '4'
                      - '5'
                      - '6'
                      - '7'
                    description: >-
                      Average gross earnings by ISO day-of-week (1=Monday,
                      7=Sunday)
                  averageByHourOfDay:
                    type: object
                    additionalProperties:
                      type: number
                    description: >-
                      Average gross earnings by hour-of-day in the selected
                      timezone (0-23)
                  period:
                    type: object
                    properties:
                      startDate:
                        type:
                          - string
                          - 'null'
                      endDate:
                        type:
                          - string
                          - 'null'
                      granularity:
                        type: string
                        enum:
                          - day
                          - week
                      timezone:
                        type: string
                    required:
                      - startDate
                      - endDate
                      - granularity
                      - timezone
                required:
                  - totals
                  - breakdownBySource
                  - earningsByType
                  - overTime
                  - averageByDayOfWeek
                  - averageByHourOfDay
                  - period
              example:
                totals:
                  allTime:
                    gross: 1250000
                    net: 1037500
                  thisMonth:
                    gross: 120000
                    net: 99000
                    previousMonthGross: 100000
                    previousMonthNet: 82500
                    grossChangePercentage: 20
                    netChangePercentage: 20
                breakdownBySource:
                  subs:
                    gross: 50000
                    net: 41250
                  messages:
                    gross: 15000
                    net: 12375
                  posts:
                    gross: 25000
                    net: 20625
                  tips:
                    gross: 12000
                    net: 9900
                  referrals:
                    gross: 4000
                    net: 3300
                  renewals:
                    gross: 10000
                    net: 8250
                  other:
                    gross: 4000
                    net: 3300
                earningsByType:
                  renewals:
                    gross: 10000
                    net: 8250
                  messages:
                    gross: 15000
                    net: 12375
                  tips:
                    gross: 12000
                    net: 9900
                  subs:
                    gross: 50000
                    net: 41250
                overTime:
                  - periodStart: '2026-03-01T00:00:00.000Z'
                    gross: 24000
                    net: 19800
                  - periodStart: '2026-03-02T00:00:00.000Z'
                    gross: 18000
                    net: 14850
                averageByDayOfWeek:
                  '1': 11000
                  '2': 9500
                  '3': 10250
                  '4': 9800
                  '5': 12000
                  '6': 8700
                  '7': 9100
                averageByHourOfDay:
                  '0': 0
                  '1': 0
                  '2': 0
                  '3': 0
                  '4': 0
                  '5': 0
                  '6': 0
                  '7': 0
                  '8': 1200
                  '9': 2300
                  '10': 2800
                  '11': 3200
                  '12': 3500
                  '13': 3700
                  '14': 4200
                  '15': 3900
                  '16': 3300
                  '17': 3000
                  '18': 2600
                  '19': 2100
                  '20': 1700
                  '21': 1300
                  '22': 900
                  '23': 400
                period:
                  startDate: '2026-03-01T00:00:00.000Z'
                  endDate: '2026-04-01T00:00:00.000Z'
                  granularity: day
                  timezone: UTC
        '400':
          description: >-
            Bad Request - API version not supported OR validation failed (dates,
            sources, cursor, pagination)
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UnsupportedVersionError'
                  - $ref: '#/components/schemas/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/UnauthorizedResponse'
        '410':
          $ref: '#/components/responses/SunsetVersionResponse'
        '429':
          $ref: '#/components/responses/RateLimitResponse'
      security:
        - BearerAuth:
            - read:insights
components:
  parameters:
    ApiVersionHeader:
      name: X-Fanvue-API-Version
      in: header
      required: true
      schema:
        type: string
        default: '2025-06-26'
        example: '2025-06-26'
      description: API version to use for the request
  schemas:
    UnsupportedVersionError:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      required:
        - error
        - message
      description: API version not supported
    ValidationError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
      required:
        - errors
      description: Request validation failed
  responses:
    UnauthorizedResponse:
      description: Unauthorized Response
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
            required:
              - error
    SunsetVersionResponse:
      description: API version no longer supported (sunset)
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              message:
                type: string
              nextVersion:
                type: string
            required:
              - error
              - message
    RateLimitResponse:
      description: Too many requests - rate limit exceeded
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request
          schema:
            type: integer
        X-RateLimit-Limit:
          description: The maximum number of requests allowed in the current window
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: The number of requests remaining in the current window
          schema:
            type: integer
        X-RateLimit-Reset:
          description: The Unix timestamp (seconds) when the rate limit window resets
          schema:
            type: integer
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
            required:
              - error
  securitySchemes:
    BearerAuth:
      type: oauth2
      description: >-
        OAuth 2.0 access token, presented as a JWT bearer token in the
        `Authorization` header. Obtain a token via the authorization-code flow;
        the scopes granted to the token determine which operations it may call.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.fanvue.com/oauth2/auth
          tokenUrl: https://auth.fanvue.com/oauth2/token
          refreshUrl: https://auth.fanvue.com/oauth2/token
          scopes:
            read:self: >-
              Access your own user profile information, including basic account
              details and settings.
            read:chat: >-
              Read chat conversations, messages, and chat-related data. This
              includes viewing chat lists and message history.
            write:chat: >-
              Create new chats and send messages. This scope is required for any
              chat-related actions that modify data.
            read:experience: >-
              Exchange a fan's experience token for the resolved experience and
              the fan's identity, so an embedded fan-facing experience can
              render the right content.
            write:experience: >-
              Request that the creator publish or unpublish a fan-facing
              experience. The app mints a request token; the creator confirms
              and Fanvue performs the change.
            read:fan: Access fan-related data and information within the platform.
            read:post: Read posts, including post details, comments, likes, and tips.
            write:post: Create, edit, and manage posts and content on behalf of users.
            read:media: Access media files, images, videos, and other content assets.
            write:media: >-
              Upload, modify, and manage media files and content assets. Also
              required for vault folder management.
            read:creator: >-
              Access creator profiles, content, and creator-specific
              information.
            write:creator: Modify creator profiles, settings, and creator-specific data.
            read:insights: >-
              Access analytics, metrics, and insights data for performance
              tracking.
            read:tracking_links: >-
              Read tracking links and the users associated with them, including
              per-user tracking metadata.
            write:tracking_links: Create and delete tracking links.
            read:agency: Read agency information, including the agency's team members.
            write:agency: >-
              Manage agency team members and invites, including inviting new
              team members and creators.

````