Outbrain Reporting API

openapi: 3.2.0
info:
  title: Outbrain Reporting API
  version: '1.0'
  description: 'Operations tagged Reporting across 2 of this provider''s published API definitions: outbrain-reporting-api-openapi.yml, outbrain-teads-report-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.outbrain.com/amplify/v0.1
  description: Production Server
- url: https://api.teads.tv/v1/analytics
  description: Teads Analytics reporting endpoint
tags:
- name: Reporting
  description: Performance reporting
paths:
  /reports/marketers/{marketerId}/campaigns:
    get:
      summary: Performance Report By Campaign
      description: 'Retrieve performance metrics (impressions, clicks, spend, conversions, CPA, CTR) aggregated by campaign for the given marketer and date range. Limited to 10 requests per minute per marketer.

        '
      operationId: reportPerformanceByCampaign
      tags:
      - Reporting
      parameters:
      - $ref: '#/components/parameters/MarketerIdPath'
      - $ref: '#/components/parameters/FromDateQuery'
      - $ref: '#/components/parameters/ToDateQuery'
      - $ref: '#/components/parameters/BreakdownQuery'
      responses:
        '200':
          description: Performance report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerformanceReport'
      security:
      - OBTokenAuth: []
    servers:
    - url: https://api.outbrain.com/amplify/v0.1
      description: Production Server
  /reports/marketers/{marketerId}/periodicContent:
    get:
      summary: Performance Report By Periodic Content
      description: Retrieve performance by promoted link over a period.
      operationId: reportPerformanceByPeriodicContent
      tags:
      - Reporting
      parameters:
      - $ref: '#/components/parameters/MarketerIdPath'
      - $ref: '#/components/parameters/FromDateQuery'
      - $ref: '#/components/parameters/ToDateQuery'
      responses:
        '200':
          description: Performance report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerformanceReport'
      security:
      - OBTokenAuth: []
    servers:
    - url: https://api.outbrain.com/amplify/v0.1
      description: Production Server
  /reports/marketers/{marketerId}/realtime:
    get:
      summary: Real Time Performance Report
      description: 'Retrieve real-time performance metrics for a marketer. Limited to 50 requests per minute per marketer.

        '
      operationId: reportPerformanceRealtime
      tags:
      - Reporting
      parameters:
      - $ref: '#/components/parameters/MarketerIdPath'
      responses:
        '200':
          description: Real-time performance report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerformanceReport'
      security:
      - OBTokenAuth: []
    servers:
    - url: https://api.outbrain.com/amplify/v0.1
      description: Production Server
  /custom:
    post:
      operationId: createReport
      summary: Processing report
      description: "Trigger an asynchronous report processing\n\nResponse JSON body attributes:\n\n- \nid (String):  unique identifier\n\n- \nstart (Timestamp ISO 8601): timestamp when the report request was registered in Teads backend\n\n- \nlastStatusUpdate (Timestamp ISO 8601): timestamp of the last internal status update in Teads backend,\n\n- \nstatus (String): report status, it can following values:\n\n- queued Teads platform has put the report in the queue to be processed, this stage may vary depending on our resources availability\n- processing The report is now being computed\n- error An issue prevented the report from being computed, please look at message field for more details\n- finished The report is now finished, you can download the result at url field.\n- killed The report was canceled during its process\n\n- \nvalid (Boolean): true if the format and content report request is valid and is being process\n\n- \nreportProgress (Object): object containing report progress\n\n- stepMax (Number): number of steps to finish report\n- step (Number): current step in the report\n- progressMax (Number): max progress to finish step\n- progress (Number): current progress in the step\n\nAll filters, except for date are optional.  emails and format are also optional groups. If not present, they will use their \"default\" value which are presented in the example above.\nFilters fields are based on ids, ie use placements : [ 1 ] for filtering on placement with id 1.\nExceptions are _status that take the status as stored in database, ie 1 for active and format which takes string format, ie inread for inread insertion/placement.\n\nWarning: format filtering can lead to long or failing requests, due to the amount of computing power it requires. If you encounter issues while using the format filter, we recommend dropping it and filtering afterwards if necessary.\n\nParameters\n\n    \n        parameter\n        type\n        default\n        required\n        description\n    \n    \n        dimensions\n        array(text)\n        -\n        Yes\n        List of dimensions to query by\n    \n    \n        filters.date.start\n        text\n        -\n        Yes\n        Lower-bound timestamp (ISO8601 format)\n    \n    \n        filters.date.end\n        text\n        -\n        Yes\n        Upper-bound timestamp (ISO8601 format)\n    \n    \n        filters.date.timezone\n        text\n        inferred from filters.date.start timestamp\n        -\n        The timezone you would like the report to be rendered in: used to resolve DST shifts (should be provided if filters.date.start is specified in UTC/GMT)\n    \n    \n        metrics\n        array(text)\n        -\n        Yes\n        List of metrics to return\n    \n    \n        emails\n        array(text)\n        []\n        -\n        E-mail addresses of report recipients\n    \n    \n        filters.ad_sources\n        array(int)\n        []\n        -\n        filter of adsource id (ex: Google DBM id \"3\")\n    \n    \n        filters.ad_status\n        array(int)\n        []\n        -\n        filter on ad status id (ex: status \"1\", active)\n    \n    \n        filters.ads\n        array(int)\n        []\n        -\n        filter on ad id (ex: ad id \"1\")\n    \n    \n        filters.adsources\n        array(int)\n        []\n        -\n        filter on connection id (ex: connection id \"1\")\n    \n    \n        filters.advertisers\n        array(int)\n        []\n        -\n        filter on advertiser id (ex: advertiser id \"1\")\n    \n    \n        filters.browser\n        array(text)\n        []\n        -\n        filter on browser name (ex: browser \"Chrome\")\n    \n    \n        filters.connection_buy_type\n        array(text)\n        []\n        -\n        filter on connection_buy_type (ex: type \"rtb\")\n    \n    \n        filters.country\n        array(text)\n        []\n        -\n        (in ISO 3166-1 alpha-2 format, ex: US, FR)\n    \n    \n        filters.creatives\n        array(int)\n        []\n        -\n        \n    \n    \n        filter on creative id (ex: creative id \"1\")\n    \n    \n        filters.demand_source\n        arr"
      tags:
      - Reporting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              filters:
                ads: []
                adsources: []
                advertisers: []
                ad_sources: []
                ad_status: []
                browser: []
                country: []
                connection_buy_type: []
                creatives: []
                device: []
                formats: []
                insertions: []
                insertion_status: []
                operating_system: []
                packs: []
                page: []
                placements:
                - 17270
                placement_status: []
                publishers: []
                scenarios: []
                websites: []
                date:
                  start: '2020-01-01T00:00:00+01:00'
                  end: '2020-01-01T23:59:00+01:00'
                  timezone: Europe/Paris
              dimensions:
              - day
              - placement
              metrics:
              - start
              - complete
              - click
              - impression
              - firstQuartile
              - midpoint
              - thirdQuartile
              - teads_billing
              emails:
              - myemail@teads.tv
              format: xlsx
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: object
              example:
                id: abcdefgh-cff2-4753-a08b-ee4587de4e9d
                start: '2020-12-14T16:35:05.269Z'
                lastStatusUpdate: '2020-12-14T16:35:05.269Z'
                status: queued
                valid: true
                reportProgress:
                  stepMax: 4
        '400':
          description: Response
          content:
            application/json:
              schema:
                type: object
              example:
                obj.dimensions.dimensions.filters.insertions[0]:
                - msg: error.expected.jsnumber
                  args: []
        '401':
          description: Unauthorized - missing or invalid OAuth bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - unknown report id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests - rate limit reached; a Retry-After header states the wait in seconds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
      security:
      - BearerAuth: []
    servers:
    - url: https://api.teads.tv/v1/analytics
      description: Teads Analytics reporting endpoint
  /custom/{id}:
    get:
      operationId: getReportStatus
      summary: Get report status
      description: "Get the status of a report that is currently processing\n\nResponse JSON body attributes (list may not be exhaustive):\n\nlist[(Object)]:\n\n- \nid (String):  unique identifier\n\n- \nstatus (String):\n\n- queued Teads platform has put the report in the queue to be processed, this stage may vary depending on our resources availability\n- processing The report is now being computed\n- error An issue prevented the report from being computed, please look at message field for more details\n- finished The report is now finished, you can download the result at url field.\n- killed The report was canceled during its process\n\n- \nstart (Timestamp ISO 8601): timestamp when the report request was registered in Teads backend\n\n- \nreportProgress (Object): object containing report progress\n\n- stepMax (Number): number of steps to finish report\n- step (Number): current step in the report\n- progressMax (Number): max progress to finish step\n- progress (Number): current progress in the step"
      tags:
      - Reporting
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Report identifier returned by POST /custom.
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: object
              example:
                id: abcdefgh-cff2-4753-a08b-ee4587de4e9d
                start: '2020-12-14T16:35:05.269Z'
                lastStatusUpdate: '2020-12-14T16:35:05.269Z'
                status: processing
                valid: true
                reportProgress:
                  stepMax: 4
                  step: 1
                  progress: 1
                  progressMax: 2
        '404':
          description: Response
          content:
            text/plain:
              schema:
                type: string
              example: The requested resource could not be found but may be available again in the future.
        '400':
          description: Bad Request - malformed report definition; body carries the REPORTING.ERROR.* code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - missing or invalid OAuth bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests - rate limit reached; a Retry-After header states the wait in seconds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
      security:
      - BearerAuth: []
    servers:
    - url: https://api.teads.tv/v1/analytics
      description: Teads Analytics reporting endpoint
  /running/list:
    get:
      operationId: listProcessingReports
      summary: List processing reports
      description: "List reports that are currently processing.\n\nResponse JSON body attributes (list may not be exhaustive):\n\nlist[(Object)]:\n\n- \nid (String):  unique identifier\n\n- \nstatus (String):\n\n- queued Teads platform has put the report in the queue to be processed, this stage may vary depending on our resources availability\n- processing The report is now being computed\n\n- \nstart (Timestamp ISO 8601): timestamp when the report request was registered in Teads backend"
      tags:
      - Reporting
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
              example:
              - id: abcdefgh-cff2-4753-a08b-ee4587de4e9d
                status: processing
                start: '2020-01-28T07:37:55.273Z'
        '400':
          description: Bad Request - malformed report definition; body carries the REPORTING.ERROR.* code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - missing or invalid OAuth bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - unknown report id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests - rate limit reached; a Retry-After header states the wait in seconds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
      security:
      - BearerAuth: []
    servers:
    - url: https://api.teads.tv/v1/analytics
      description: Teads Analytics reporting endpoint
  /custom/{id}/kill:
    put:
      operationId: cancelReport
      summary: Cancel processing report
      description: "Cancel a report that is currently processing\n\nResponse JSON body attributes (list may not be exhaustive):\n\n- \nstatus (String):\n\n- killed The report was canceled during its process\n\n- \nid (String): unique identifier"
      tags:
      - Reporting
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Report identifier returned by POST /custom.
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: object
              example:
                status: killed
                id: '{{report_id}}'
        '400':
          description: Response
          content:
            application/json:
              schema:
                type: object
              example:
                status: 400
                msg: REPORTING.ERROR.APPLICATION_NOT_FOUND
        '401':
          description: Unauthorized - missing or invalid OAuth bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - unknown report id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests - rate limit reached; a Retry-After header states the wait in seconds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
      security:
      - BearerAuth: []
    servers:
    - url: https://api.teads.tv/v1/analytics
      description: Teads Analytics reporting endpoint
components:
  parameters:
    FromDateQuery:
      name: from
      in: query
      required: true
      schema:
        type: string
        format: date
      description: Start date of the report range (YYYY-MM-DD).
    BreakdownQuery:
      name: breakdown
      in: query
      required: false
      schema:
        type: string
        enum:
        - day
        - week
        - month
        - campaign
        - country
        - platform
      description: Breakdown dimension for the report.
    ToDateQuery:
      name: to
      in: query
      required: true
      schema:
        type: string
        format: date
      description: End date of the report range (YYYY-MM-DD).
    MarketerIdPath:
      name: marketerId
      in: path
      required: true
      schema:
        type: string
      description: Marketer (customer account) identifier.
  schemas:
    PerformanceReport:
      type: object
      properties:
        marketerId:
          type: string
        from:
          type: string
          format: date
        to:
          type: string
          format: date
        results:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              impressions:
                type: integer
              clicks:
                type: integer
              spend:
                type: number
              conversions:
                type: integer
              ctr:
                type: number
              cpc:
                type: number
              cpa:
                type: number
    Error:
      type: object
      description: Teads reporting error envelope.
      properties:
        status:
          type: integer
        msg:
          type: string
          description: REPORTING.ERROR.* code
      examples:
      - status: 400
        msg: REPORTING.ERROR.APPLICATION_NOT_FOUND
  securitySchemes:
    OBTokenAuth:
      type: apiKey
      in: header
      name: OB-TOKEN-V1
      description: Token returned from /login. Send on all authenticated requests.
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
      description: Teads OAuth bearer token supplied in the Authorization header. Requires a Teads platform account with reporting rights.
x-refined-from:
- outbrain-reporting-api-openapi.yml
- outbrain-teads-report-api-openapi.yml