News Break Reporting API

openapi: 3.2.0
info:
  title: NewsBreak MSP Monetization Reporting API
  version: v0.1
  description: 'The NewsBreak MSP API for Business is the monetization-side interface NewsBreak provides to supply partners and publishers running the NewsBreak MSP (monetization service platform). The Reporting API returns aggregated ad monetization performance — impressions, revenue, publisher net revenue, eCPM, fill and request counts, clicks and CTR — broken down by date, operating system, bidder seat, placement, bidder ad unit and device type.


    This document was generated by API Evangelist from the operations NewsBreak publishes at https://doc.msp.newsbreak.com/business-api-doc/docs/api-reference/. NewsBreak does not publish a machine-readable OpenAPI definition for this API; every path, parameter, enumeration and response field here is transcribed from the published reference. A `/swagger.json` path does exist on the API host but returns HTTP 200 with a zero-byte body, so it is not a usable contract.'
  contact:
    name: NewsBreak Ad Support
    email: adsupport@newsbreak.com
    url: https://doc.msp.newsbreak.com/
  termsOfService: https://www.newsbreak.com/terms
servers:
- url: https://msp-platform.newsbreak.com
  description: NewsBreak MSP platform production
security:
- ApiToken: []
tags:
- name: Reporting
  description: Aggregated monetization performance reporting for MSP organizations and apps.
paths:
  /reporting:
    get:
      operationId: getMonetizationReport
      tags:
      - Reporting
      summary: Get a monetization report
      description: Return a monetization performance report for an organization and app over a date range, optionally broken down by dimension and restricted to a chosen metric set. Credentials (`org_id`, `app_id`, `token`) are passed as query parameters.
      externalDocs:
        url: https://doc.msp.newsbreak.com/business-api-doc/docs/api-reference/reporting/reporting-api
      parameters:
      - name: org_id
        in: query
        required: true
        description: Organization ID.
        schema:
          type: integer
      - name: app_id
        in: query
        required: true
        description: App ID.
        schema:
          type: integer
      - name: token
        in: query
        required: true
        description: API token.
        schema:
          type: string
      - name: start_date
        in: query
        required: true
        description: Start date of the report, formatted YYYY-MM-DD.
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        required: true
        description: End date of the report, formatted YYYY-MM-DD.
        schema:
          type: string
          format: date
      - name: timezone
        in: query
        required: false
        description: Report timezone. Defaults to UTC.
        schema:
          type: string
          enum:
          - PT
          - ET
          - UTC
          - Beijing Time
          default: UTC
      - name: breakdown
        in: query
        required: false
        description: Dimensions to break the report down by. None are selected by default. Repeat the parameter for multiple dimensions.
        schema:
          type: array
          items:
            type: string
            enum:
            - date
            - os
            - seat
            - placement_id
            - seat_ad_unit
            - device_type
      - name: metrics
        in: query
        required: false
        description: Metrics to return. Defaults to revenue, imp and ecpm. Repeat the parameter for multiple metrics.
        schema:
          type: array
          items:
            type: string
            enum:
            - imp
            - revenue
            - ecpm
            - payout_revenue
            - fill_count
            - request_count
            - click
            - ctr
      - name: filter
        in: query
        required: false
        description: Filter value. Requires the corresponding breakdown dimension to be selected.
        schema:
          type: string
          enum:
          - os
          - seat
          - placement_id
      responses:
        '200':
          description: A report. On success the body is an array of report rows. On failure the body carries a non-zero `code` and an `errMsg` (see Return Codes).
          content:
            application/json:
              schema:
                oneOf:
                - type: array
                  items:
                    $ref: '#/components/schemas/ReportRow'
                - $ref: '#/components/schemas/Envelope'
              examples:
                rows:
                  summary: Report rows broken down by date and bidder seat
                  value:
                  - app_id: 2
                    seat: bidderA
                    date: '2024-12-15'
                    ecpm: 110.0
                    org_id: 111
                    revenue: 11
                  - app_id: 2
                    seat: bidderA
                    date: '2024-12-16'
                    ecpm: 135.1899
                    org_id: 111
                    revenue: 534
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
components:
  schemas:
    ReportRow:
      type: object
      description: One row of monetization report data.
      properties:
        date:
          type: string
          description: Date.
        org_id:
          type: integer
          description: Organization ID.
        app_id:
          type: integer
          description: App ID.
        os:
          type: string
          description: Operating system.
        seat:
          type: string
          description: Bidder.
        placement_name:
          type: string
          description: Placement name.
        imp:
          type: integer
          description: Impression count.
        revenue:
          type: number
          format: float
          description: Revenue in USD.
        payout_revenue:
          type: number
          format: float
          description: Publisher net revenue in USD.
        ecpm:
          type: number
          format: float
          description: Gross eCPM.
        seat_ad_unit:
          type: string
          description: Bidder ad unit name.
        click:
          type: integer
          description: Click count.
    Envelope:
      type: object
      description: The error envelope. `code` 0 is successful; any other value is an error described by `errMsg` (see Return Codes).
      properties:
        code:
          type: integer
          description: Status code. 0 is successful.
        errMsg:
          type: string
          description: Error message when the return code is not 0.
        list:
          type: array
          description: Report rows.
          items:
            $ref: '#/components/schemas/ReportRow'
  securitySchemes:
    ApiToken:
      type: apiKey
      in: query
      name: token
      description: API token issued to the MSP organization, passed as the `token` query parameter alongside `org_id` and `app_id`.
externalDocs:
  description: NewsBreak API for business documentation
  url: https://doc.msp.newsbreak.com/business-api-doc/docs/overview/