openapi: 3.2.0
info:
  title: NewsBreak Advertising Report API
  version: v1
  description: 'The NewsBreak Advertising API (NewsBreak API for Business) lets technology companies, direct advertisers and agencies programmatically manage the NewsBreak Ads Manager at scale: create and manage organizations, ad accounts and ad-account users; build campaigns, ad sets and ads; upload creative assets to the NewsBreak CDN; configure audience targeting and inventory platforms; manage account spending caps; read conversion tracking events; and run multidimensional performance reports.


    This document was generated by API Evangelist from the operations NewsBreak publishes in its Ad Manager API reference (https://advertising-api.newsbreak.com/hc/en-us). NewsBreak does not publish a machine-readable OpenAPI definition; every path, method, parameter, enumeration and response field here is transcribed from the published reference articles, which are linked per operation via externalDocs.'
  termsOfService: https://www.newsbreak.com/terms
  contact:
    name: NewsBreak Ad Support
    email: adsupport@newsbreak.com
    url: https://advertising-api.newsbreak.com/hc/en-us
servers:
- url: https://business.newsbreak.com/business-api/v1
  description: NewsBreak Advertising API production
security:
- AccessToken: []
tags:
- name: Report
  description: Synchronous and saved custom performance reports.
paths:
  /reports/getIntegratedReport:
    post:
      operationId: runSynchronousReport
      tags:
      - Report
      summary: Run a synchronous report
      description: Run a synchronous report task and return the rows inline.
      externalDocs:
        description: 'NewsBreak reference: Run a Synchronous Report'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37825594764941-Run-a-Synchronous-Report
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRequest'
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportRowsResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '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'
  /reports/createReport:
    post:
      operationId: createCustomReport
      tags:
      - Report
      summary: Create a custom report
      description: Create a saved custom report definition that can later be run by ID.
      externalDocs:
        description: 'NewsBreak reference: Create a Custom Report'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37825592263053-Create-a-Custom-Report
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRequest'
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportRowsResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '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'
  /reports/getReportById:
    get:
      operationId: getCustomReportById
      tags:
      - Report
      summary: Get a custom report by ID
      description: Run a previously created custom report and return its rows.
      externalDocs:
        description: 'NewsBreak reference: Get a Custom Report by Id'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37825650131469-Get-a-Custom-Report-by-Id
      parameters:
      - name: reportId
        in: query
        required: true
        description: ID of this report.
        schema:
          type: string
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportRowsResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '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:
    ReportRowsResponse:
      type: object
      description: Envelope carrying report rows.
      properties:
        code:
          type: integer
          description: Status code. 0 is successful; see Return Codes.
        errMsg:
          type: string
          description: Error message when code != 0.
        data:
          type: object
          properties:
            rows:
              type: array
              items:
                $ref: '#/components/schemas/ReportRow'
    ReportRow:
      type: object
      description: One row of report data.
      properties:
        date:
          type: string
          description: Date.
        hour:
          type: string
          description: Hour.
        adAccountId:
          type: string
          description: Ad account ID.
        adAccount:
          type: string
          description: Ad account name.
        orgId:
          type: string
          description: Organization ID.
        organization:
          type: string
          description: Organization name.
        campaignId:
          type: string
          description: Campaign ID.
        campaign:
          type: string
          description: Campaign name.
        adSetId:
          type: string
          description: Ad set ID.
        adSet:
          type: string
          description: Ad set name.
        adId:
          type: string
          description: Ad ID.
        ad:
          type: string
          description: Ad name.
        placement:
          type: string
          description: Placement name.
        country:
          type: string
          description: Country name.
        costDecimal:
          type: number
          format: double
          description: Cost in cents.
        cost:
          type: integer
          description: Cost in cents.
        impression:
          type: integer
          description: Impressions.
        click:
          type: integer
          description: Clicks.
        conversion:
          type: integer
          description: Conversions.
        conversionValueDecimal:
          type: number
          format: double
          description: Total conversion value in cents.
        conversionValue:
          type: integer
          description: Total conversion value.
        cpmDecimal:
          type: number
          format: double
          description: CPM in cents, -1.0 if N/A.
        cpm:
          type: integer
          description: CPM in cents, -1 if N/A.
        cpcDecimal:
          type: number
          format: double
          description: CPC in cents, -1.0 if N/A.
        cpc:
          type: integer
          description: CPC in cents, -1 if N/A.
        cpaDecimal:
          type: number
          format: double
          description: Cost per action in cents, -1.0 if N/A.
        cpa:
          type: integer
          description: Cost per action in cents, -1 if N/A.
        ctr:
          type: number
          description: Click-through rate.
    Envelope:
      type: object
      description: The standard NewsBreak response envelope. Every operation returns HTTP 200 with a `code` field; code 0 means success and any other value is an error (see Return Codes).
      properties:
        code:
          type: integer
          description: Status code. 0 is successful; see Return Codes.
        errMsg:
          type: string
          description: Error message when code != 0.
        data:
          type: object
          description: Response object.
    ReportRequest:
      type: object
      description: A report definition, shared by runSynchronousReport and createCustomReport.
      properties:
        name:
          type: string
          description: Name of this report.
        timezone:
          type: string
          description: Valid timezone string, such as UTC, America/Los_Angeles or Asia/Shanghai. Default is PDT.
        dateRange:
          type: string
          description: Date range of the report.
          enum:
          - FIXED
          - YESTERDAY
          - LAST_7_DAYS
          - LAST_14_DAYS
          - LAST_30_DAYS
          - MONTH_TO_DATE
          - QUARTER_TO_DATE
          - TODAY
        startDate:
          type: string
          description: Start date, formatted YYYY-MM-DD. Required when dateRange is FIXED.
        endDate:
          type: string
          description: End date, formatted YYYY-MM-DD. Required when dateRange is FIXED.
        filter:
          type: string
          description: Filter type.
          enum:
          - ORG
          - AD_ACCOUNT
          - CAMPAIGN
          - AD_SET
          - AD
        dataSource:
          type: string
          description: Data source type. HOURLY is the official basis for income settlement on NewsBreak.
          enum:
          - HOURLY
          - REALTIME
        filterIds:
          type: array
          description: IDs matching the filter type.
          items:
            type: string
        dimensions:
          type: array
          description: Report dimensions (UPPERCASE only). HOUR only works with dateRange YESTERDAY, TODAY or a 1-day FIXED range; DATE works with YESTERDAY, TODAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, MONTH_TO_DATE or a FIXED range of at most 30 days.
          items:
            type: string
            enum:
            - DATE
            - HOUR
            - ORG
            - AD_ACCOUNT
            - CAMPAIGN
            - AD_SET
            - AD
            - PLACEMENT
        metrics:
          type: array
          description: Report metrics.
          items:
            type: string
        emails:
          type: array
          description: Email recipients of the report.
          items:
            type: string
        editors:
          type: array
          description: Users allowed to edit the report.
          items:
            type: string
      required:
      - name
      - timezone
      - dateRange
      - dimensions
      - metrics
  securitySchemes:
    AccessToken:
      type: apiKey
      in: header
      name: Access-Token
      description: Authorized access token. Generate it in the NewsBreak Ad Manager under Resources -> API Access Tokens ("Generate Token"). The token carries the permissions granted by the advertiser. Keep it secret.
externalDocs:
  description: NewsBreak Ad Manager API reference
  url: https://advertising-api.newsbreak.com/hc/en-us