openapi: 3.2.0
info:
  title: Disconetwork Discobeat API
  version: '1.0'
  description: 'Operations tagged Discobeat across 2 of this provider''s published API definitions: disconetwork-reporting-api-v1.yml, disconetwork-reporting-api-v2.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.disconetwork.com
  description: Disco API
security:
- ManagementApiKey: []
tags:
- name: Discobeat
paths:
  /discobeat/reporting/v1/summary/:
    get:
      summary: Channel summary
      description: Channel-level metric totals across all your publishers for a date range.
      operationId: getReportingSummary
      parameters:
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      responses:
        '200':
          description: Channel totals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummaryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
      tags:
      - Discobeat
    servers:
    - url: https://api.disconetwork.com
      description: Disco API
  /discobeat/reporting/v1/publishers/:
    get:
      summary: Publisher breakdown
      description: Per-publisher metrics.
      operationId: getReportingPublishers
      parameters:
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - name: granularity
        in: query
        required: false
        description: Time-series bucket size.
        schema:
          type: string
          enum:
          - day
          - hour
          default: day
      - name: breakdown
        in: query
        required: false
        description: Series split.
        schema:
          type: string
          enum:
          - page_type
          - widget_type
          - widget_id
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 50
      responses:
        '200':
          description: Per-publisher metrics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishersResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
      tags:
      - Discobeat
    servers:
    - url: https://api.disconetwork.com
      description: Disco API
  /discobeat/reporting/v2/report/:
    get:
      summary: Build a report
      description: 'Returns flat, paginated rows plus summary metrics across the complete filtered result. The response includes only the requested metrics and selected breakdown columns.

        '
      operationId: getReportingV2Report
      parameters:
      - $ref: '#/components/parameters/From_2'
      - $ref: '#/components/parameters/To_2'
      - $ref: '#/components/parameters/Metrics'
      - $ref: '#/components/parameters/TimeGrain'
      - $ref: '#/components/parameters/GroupBy'
      - $ref: '#/components/parameters/PublisherIds'
      - $ref: '#/components/parameters/PageTypes'
      - $ref: '#/components/parameters/WidgetTypes'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Paginated report rows and complete matching summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'
        '400':
          $ref: '#/components/responses/BadRequest_2'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '405':
          $ref: '#/components/responses/MethodNotAllowed_2'
      tags:
      - Discobeat
    servers:
    - url: https://api.disconetwork.com
      description: Disco API
components:
  schemas:
    CalculatedMetrics:
      description: Derived from raw metrics. Ratios are rounded to four decimals. Zero denominators return 0.
      type: object
      required:
      - ctr
      - cvr
      - rps
      - rpl
      properties:
        ctr:
          type: number
          format: float
          example: 0.028
        cvr:
          type: number
          format: float
          example: 0.05
        rps:
          type: number
          format: float
          example: 0.04
        rpl:
          type: number
          format: float
          example: 0.0375
    RawMetrics:
      type: object
      required:
      - impressions
      - clicks
      - conversions
      - channel_payout
      - revenue_with_email
      - revenue_without_email
      - sessions
      - feed_loads
      properties:
        impressions:
          type: integer
          example: 480000
        clicks:
          type: integer
          example: 13440
        conversions:
          type: integer
          example: 672
        channel_payout:
          type: number
          format: float
          example: 9600.0
        revenue_with_email:
          type: number
          format: float
          example: 7200.0
        revenue_without_email:
          type: number
          format: float
          example: 2400.0
        sessions:
          type: integer
          example: 240000
        feed_loads:
          type: integer
          example: 256000
    DateRange:
      type: object
      required:
      - from
      - to
      properties:
        from:
          type: string
          format: date
          example: '2026-06-08'
        to:
          type: string
          format: date
          example: '2026-06-14'
    SeriesPoint:
      type: object
      required:
      - bucket
      - metrics
      properties:
        bucket:
          type: string
          description: A date (granularity=day) or an ISO hour timestamp (granularity=hour).
          example: '2026-06-14'
        page_type:
          type:
          - string
          - 'null'
          description: Present when breakdown=page_type.
          example: ORDER_TRACKING
        widget_type:
          type:
          - string
          - 'null'
          description: Present when breakdown=widget_type.
          example: APP_NATIVE_ESSENTIAL
        widget_id:
          type:
          - string
          - 'null'
          maxLength: 64
          description: Present when breakdown=widget_id.
        metrics:
          $ref: '#/components/schemas/MetricBlock'
    PublishersResponse:
      type: object
      required:
      - channel_id
      - channel_name
      - date_range
      - available_window
      - granularity
      - breakdown
      - has_data
      - publishers
      - pagination
      - data_freshness
      - generated_at
      properties:
        channel_id:
          type: string
          example: 7c3e1a90-4b2d-4f8a-9c11-2e6b5a0d8f34
        channel_name:
          type: string
          example: Acme
        date_range:
          $ref: '#/components/schemas/DateRange'
        available_window:
          $ref: '#/components/schemas/AvailableWindow'
        granularity:
          type: string
          enum:
          - day
          - hour
          example: day
        breakdown:
          type:
          - string
          - 'null'
          enum:
          - page_type
          - widget_type
          - widget_id
          example: page_type
        has_data:
          type: boolean
          example: true
        publishers:
          type: array
          items:
            $ref: '#/components/schemas/PublisherRow'
        pagination:
          $ref: '#/components/schemas/Pagination'
        data_freshness:
          type:
          - string
          - 'null'
          example: '2026-06-14T05:00:00'
        generated_at:
          type:
          - string
          - 'null'
          example: '2026-06-14T05:25:11'
    AvailableWindow:
      type: object
      required:
      - from
      - to
      description: Date range currently available from this reporting source.
      properties:
        from:
          type: string
          format: date
          example: '2026-05-26'
        to:
          type: string
          format: date
          example: '2026-06-30'
    AuthError:
      type: object
      required:
      - detail
      properties:
        detail:
          type: string
          example: Invalid or expired management API key.
    AvailabilityError:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - REPORTING_DATA_UNAVAILABLE
          - DATE_RANGE_OUTSIDE_AVAILABLE_WINDOW
        message:
          type: string
        available_window:
          $ref: '#/components/schemas/AvailableWindow'
    PublisherRow:
      type: object
      required:
      - publisher_uuid
      - publisher_name
      - publisher_category
      - metrics
      - series
      properties:
        publisher_uuid:
          type: string
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        publisher_name:
          type: string
          example: Acme Tracking Page
        publisher_category:
          type:
          - string
          - 'null'
          example: Logistics
        metrics:
          $ref: '#/components/schemas/MetricBlock'
        series:
          type: array
          items:
            $ref: '#/components/schemas/SeriesPoint'
    SummaryResponse:
      type: object
      required:
      - channel_id
      - channel_name
      - date_range
      - available_window
      - has_data
      - metrics
      - data_freshness
      - generated_at
      properties:
        channel_id:
          type: string
          example: 7c3e1a90-4b2d-4f8a-9c11-2e6b5a0d8f34
        channel_name:
          type: string
          example: Acme
        date_range:
          $ref: '#/components/schemas/DateRange'
        available_window:
          $ref: '#/components/schemas/AvailableWindow'
        has_data:
          type: boolean
          example: true
        metrics:
          $ref: '#/components/schemas/MetricBlock'
        data_freshness:
          type:
          - string
          - 'null'
          example: '2026-06-14T05:00:00'
        generated_at:
          type:
          - string
          - 'null'
          example: '2026-06-14T05:25:11'
    MetricBlock:
      type: object
      required:
      - raw
      - calculated
      properties:
        raw:
          $ref: '#/components/schemas/RawMetrics'
        calculated:
          $ref: '#/components/schemas/CalculatedMetrics'
    Pagination:
      type: object
      required:
      - offset
      - limit
      - total
      properties:
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 50
        total:
          type: integer
          example: 1
    ValidationError:
      type: object
      additionalProperties: true
    ReportRow:
      allOf:
      - type: object
        required:
        - period_start
        - period_end
        properties:
          period_start:
            type: string
            format: date-time
            description: Inclusive UTC period boundary.
            example: '2026-07-18T00:00:00Z'
          period_end:
            type: string
            format: date-time
            description: Exclusive UTC period boundary.
            example: '2026-07-19T00:00:00Z'
          publisher_id:
            type:
            - string
            - 'null'
            example: 9aa17f8c-7746-4218-9025-83d38c406179
          publisher_name:
            type:
            - string
            - 'null'
            example: AfterShip Tracking Page
          page_type:
            type:
            - string
            - 'null'
            example: ORDER_TRACKING
          widget_type:
            type:
            - string
            - 'null'
            example: APP_NATIVE_ESSENTIAL
          widget_id:
            type:
            - string
            - 'null'
            maxLength: 64
      - $ref: '#/components/schemas/MetricValues'
    Metric:
      type: string
      enum:
      - impressions
      - clicks
      - conversions
      - channel_payout
      - revenue_with_email
      - revenue_without_email
      - sessions
      - feed_loads
      - ctr
      - cvr
      - rps
      - rpl
    MetricValues:
      type: object
      properties:
        impressions:
          type: integer
          example: 225072
        clicks:
          type: integer
          example: 8928
        conversions:
          type: integer
          example: 864
        channel_payout:
          type: number
          format: double
          example: 6546.24
        revenue_with_email:
          type: number
          format: double
          example: 4909.68
        revenue_without_email:
          type: number
          format: double
          example: 1636.56
        sessions:
          type: integer
          example: 120000
        feed_loads:
          type: integer
          example: 135000
        ctr:
          type: number
          format: double
          example: 0.0397
        cvr:
          type: number
          format: double
          example: 0.0968
        rps:
          type: number
          format: double
          example: 0.0546
        rpl:
          type: number
          format: double
          example: 0.0485
    ReportResponse:
      type: object
      required:
      - data
      - summary
      - pagination
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ReportRow'
        summary:
          $ref: '#/components/schemas/MetricValues'
        pagination:
          $ref: '#/components/schemas/Pagination_2'
        meta:
          $ref: '#/components/schemas/ReportMeta'
    ReportMeta:
      type: object
      required:
      - timezone
      - data_through
      - request_id
      properties:
        timezone:
          type: string
          enum:
          - UTC
        data_through:
          type:
          - string
          - 'null'
          format: date-time
          example: '2026-07-22T23:00:00Z'
        request_id:
          type:
          - string
          - 'null'
          example: 7e9fe348-7558-4e28-b8c6-b26ea44899eb
    ErrorResponse:
      type: object
      additionalProperties: true
    Pagination_2:
      type: object
      required:
      - offset
      - limit
      - total
      - has_more
      properties:
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 50
        total:
          type: integer
          example: 36
        has_more:
          type: boolean
          example: false
  responses:
    MethodNotAllowed:
      description: Only GET is supported.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthError'
          example:
            detail: Method "POST" not allowed.
    Unauthorized:
      description: Missing or invalid management API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthError'
          example:
            detail: Invalid or expired management API key.
    BadRequest:
      description: Invalid parameters, unsupported date range, or unavailable reporting data.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ValidationError'
            - $ref: '#/components/schemas/AvailabilityError'
          examples:
            rangeTooLarge:
              value:
                date_range:
                - Date range cannot exceed 90 days.
            badGranularity:
              value:
                granularity:
                - '"weekly" is not a valid choice.'
            outsideAvailableWindow:
              value:
                code: DATE_RANGE_OUTSIDE_AVAILABLE_WINDOW
                message: Reporting data is available from 2026-05-26 through 2026-06-30.
                available_window:
                  from: '2026-05-26'
                  to: '2026-06-30'
    MethodNotAllowed_2:
      description: Only GET is supported.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            detail: Method "POST" not allowed.
    Unauthorized_2:
      description: Missing or invalid management API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            detail: Invalid or expired management API key.
    BadRequest_2:
      description: Invalid query, unavailable metric or data, date outside the available window, or result over 10,000 rows.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            metricNotAvailable:
              value:
                code: METRIC_NOT_AVAILABLE
                unsupported_metrics:
                - channel_payout
                allowed_metrics:
                - impressions
                - clicks
                - ctr
            outsideAvailableWindow:
              value:
                code: DATE_RANGE_OUTSIDE_AVAILABLE_WINDOW
                message: Reporting data is available from 2026-05-16 through 2026-07-22.
                available_window:
                  from: '2026-05-16'
                  to: '2026-07-22'
            rowLimit:
              value:
                code: REPORT_ROW_LIMIT_EXCEEDED
                message: Report exceeds the interactive row limit. Narrow the date range or remove one or more breakdowns.
                max_rows: 10000
                total_rows: 12000
  parameters:
    From:
      name: from
      in: query
      required: false
      description: Start date YYYY-MM-DD (UTC), inclusive. Default 6 days before `to` (7-day window).
      schema:
        type: string
        format: date
    To:
      name: to
      in: query
      required: false
      description: End date YYYY-MM-DD (UTC), inclusive. Default today. Max range 90 days.
      schema:
        type: string
        format: date
    Metrics:
      name: metrics
      in: query
      required: true
      description: 'Comma-separated metrics enabled for the authenticated channel. Metrics must be unique.

        '
      style: form
      explode: false
      schema:
        type: array
        minItems: 1
        uniqueItems: true
        items:
          $ref: '#/components/schemas/Metric'
      example:
      - impressions
      - clicks
      - channel_payout
      - ctr
    Offset:
      name: offset
      in: query
      required: false
      description: Pagination offset.
      schema:
        type: integer
        minimum: 0
        default: 0
    PageTypes:
      name: page_types
      in: query
      required: false
      description: Comma-separated page-type filter. Filtering does not add a report column.
      style: form
      explode: false
      schema:
        type: array
        maxItems: 250
        items:
          type: string
      example:
      - ORDER_TRACKING
      - THANK_YOU
    From_2:
      name: from
      in: query
      required: true
      description: Start date in UTC, inclusive.
      schema:
        type: string
        format: date
        example: '2026-07-18'
    PublisherIds:
      name: publisher_ids
      in: query
      required: false
      description: Comma-separated publisher UUID filter. Filtering does not add a report column.
      style: form
      explode: false
      schema:
        type: array
        maxItems: 250
        items:
          type: string
      example:
      - 9aa17f8c-7746-4218-9025-83d38c406179
    GroupBy:
      name: group_by
      in: query
      required: false
      description: 'Comma-separated breakdown columns. Up to three are supported except hourly reports, which support at most one.

        '
      style: form
      explode: false
      schema:
        type: array
        maxItems: 3
        uniqueItems: true
        items:
          type: string
          enum:
          - publisher
          - page_type
          - widget_type
          - widget_id
      example:
      - publisher
      - page_type
    Limit:
      name: limit
      in: query
      required: false
      description: JSON page size.
      schema:
        type: integer
        minimum: 1
        maximum: 250
        default: 50
    WidgetTypes:
      name: widget_types
      in: query
      required: false
      description: Comma-separated widget-type filter. Filtering does not add a report column.
      style: form
      explode: false
      schema:
        type: array
        maxItems: 250
        items:
          type: string
      example:
      - APP_NATIVE_ESSENTIAL
    TimeGrain:
      name: time_grain
      in: query
      required: false
      description: 'UTC row interval. Hour supports at most 3 days and one breakdown. Week and month edge periods are clipped to the requested date range.

        '
      schema:
        type: string
        enum:
        - total
        - day
        - week
        - month
        - hour
        default: total
    To_2:
      name: to
      in: query
      required: true
      description: End date in UTC, inclusive. The requested range can span at most 90 days.
      schema:
        type: string
        format: date
        example: '2026-07-20'
  securitySchemes:
    ManagementApiKey:
      type: apiKey
      in: header
      name: x-api-key
x-refined-from:
- disconetwork-reporting-api-v1.yml
- disconetwork-reporting-api-v2.yml