openapi: 3.2.0
info:
  title: BidMachine Reporting API
  version: 1.0.0
  description: 'This API provides reporting data. Requirements:

    - Basic Authentication (__login and password__).

    - The maximum allowed time period for a query is **45 days** (the P2P Revenue report allows up to **2 years**).

    - Rate limit: **6 requests per minute**.

    Note:

    Report generation can take between **10** to **60 seconds** depending on server load,

    and the request timeout can be up to **300 seconds**.'
  x-apievangelist:
    source: https://developers.bidmachine.io/api/bidmachine-reporting-api
    method: searched
    harvested: '2026-09-19'
    note: 'Assembled from the provider''s own compiled OpenAPI operation objects embedded in developers.bidmachine.io (docusaurus-plugin-openapi-docs). Every path, parameter, schema, response and security scheme is the provider''s; operationId, tags and summary were added by API Evangelist (see overlays/). Verbatim decoded objects: openapi/_original/.'
servers:
- url: https://api-eu.bidmachine.io/api/v1
tags:
- name: Reporting
paths:
  /report/ssp:
    get:
      operationId: retrieveSspReportData
      summary: Retrieve SSP Report Data
      description: Returns reporting data in __NDJSON__ or __CSV__ format based on the query parameters. The endpoint accepts a date range, an optional output format, header preferences for CSV, and an optional list of fields (dimensions) to be returned.
      tags:
      - Reporting
      parameters:
      - in: query
        name: start
        required: true
        schema:
          type: string
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
        description: Start date of the interval in `"yyyy-MM-dd"` format [inclusive].
      - in: query
        name: end
        required: true
        schema:
          type: string
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
        description: End date of the interval in `"yyyy-MM-dd"` format (exclusive).
      - in: query
        name: format
        required: false
        schema:
          type: string
          enum:
          - csv
          - json
        description: 'Response report format. Use `csv` for CSV output or `json` for a JSON-string CSV.

          '
      - in: query
        name: csv_header
        required: false
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
        description: 'Applicable only when format=csv. Use 0 for CSV without a header line or 1 for CSV with a header.

          '
      - in: query
        name: fields
        required: false
        schema:
          type: array
          items:
            type: string
          style: form
          explode: false
        description: 'Comma-separated list of dimensions to include in the report. Possible values include: `date`, `country`, `publisher_id`, `app_name`, `app_bundle`, `platform`, `zero_ifa`, `ad_type`, `impressions`, `clicks`, `ctr`, `ecpm`, `revenue`, `device_type`, `imp_tagid`, `dsp_name`, `demand_partner`, `auction_floor_source`, `mediation_stack_id`, `source_id`, `integration_id`, `payer`, `is_paas`, `exchange_placement_id`, `exchange_placement_name`, `coppa`.

          '
      responses:
        '200':
          description: Successful response with report data.
          content:
            application/x-ndjson:
              schema:
                type: object
                properties:
                  date:
                    type: string
                    example: '2018-12-01'
                  country:
                    type: string
                    example: DE
                  publisher_id:
                    type: integer
                    example: 6
                  app_name:
                    type: string
                    example: App 1
                  app_bundle:
                    type: string
                    example: '111111111'
                  platform:
                    type: string
                    example: ios
                  ad_type:
                    type: string
                    example: interstitial
                  demand_partner:
                    type: string
                    description: The demand partner behind the spend.
                    example: Magnite
                  impressions:
                    type: integer
                    example: 271
                  clicks:
                    type: integer
                    example: 19
                  ctr:
                    type: number
                    format: float
                    example: 7.01
                  ecpm:
                    type: number
                    format: float
                    example: 1.550635
                  revenue:
                    type: number
                    format: float
                    example: 0.420222
                  payer:
                    type: string
                    description: Who settles the money with the publisher - BidMachine, demand partner or Google.
                    example: p2p_magnite
                  is_paas:
                    type: boolean
                    description: P2P connection where BidMachine acts as payment aggregation agent.
                    example: false
                  exchange_placement_id:
                    type: string
                    example: bjoyMGUwcjE2NmEzbjpiMV8xNTFtYjcxXw
                  exchange_placement_name:
                    type: string
                    example: Main Rewarded Placement
                  coppa:
                    type: string
                    description: COPPA applicability flag as a string value.
                    example: 'false'
            text/csv:
              schema:
                type: string
              example: 'date,country,publisher_id,app_name,app_bundle,platform,ad_type,impressions,clicks,ctr,ecpm,revenue,payer

                "2018-12-01","DE",6,"App 1","111111111","ios","skippable_video",271,19,7.01,1.550635,0.420222,"p2p_magnite"

                "2018-12-01","GB",6,"App 2","222222222","ios","skippable_video",6444,232,3.6,3.570498,23.008289,"p2p_magnite"

                '
        '400':
          description: Bad Request – missing or invalid parameters.
        '401':
          description: Unauthorized – invalid or missing authentication credentials.
        '429':
          description: Too Many Requests – rate limit exceeded.
          headers:
            ad-exchange-warn-message:
              schema:
                type: string
              description: Rate limit warning message.
              example: You've been requesting too much. Please try again in 5 seconds.
      security:
      - basicAuth: []
  /report/bidder:
    get:
      operationId: retrieveBidderReportData
      summary: Retrieve Bidder Report Data
      description: Returns bidder reporting data in __NDJSON__ or __CSV__ format based on the query parameters. The endpoint accepts an interval, an optional output format, and an optional list of fields (dimensions) to be returned.
      tags:
      - Reporting
      parameters:
      - in: query
        name: start
        required: true
        schema:
          type: string
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
        description: Start date of the interval in `"yyyy-MM-dd"` format [inclusive].
      - in: query
        name: end
        required: true
        schema:
          type: string
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
        description: End date of the interval in `"yyyy-MM-dd"` format (exclusive).
      - in: query
        name: format
        required: false
        schema:
          type: string
          enum:
          - csv
          - json
        description: 'Response report format. Use `csv` for CSV output or `json` for newline-delimited JSON.

          '
      - in: query
        name: fields
        required: false
        schema:
          type: array
          items:
            type: string
          style: form
          explode: false
        description: 'Comma-separated list of dimensions to include in the report. Possible values include: `date`, `agency_id`, `agency_name`, `is_paas`, `bidder_id`, `publisher_id`, `source_id`, `seat_id`, `adomain`, `country`, `app_bundle`, `platform`, `ad_type`, `impressions`, `clicks`, `ctr`, `spend`, `p2p_paas_fee`, `seller_income`, `bidder_endpoint`.

          '
      responses:
        '200':
          description: Successful response with report data.
          content:
            application/x-ndjson:
              schema:
                type: object
                properties:
                  date:
                    type: string
                    format: date
                    example: '2026-01-07'
                  agency_id:
                    type: integer
                    example: 283
                  agency_name:
                    type: string
                    example: Example Agency
                  is_paas:
                    type: boolean
                    description: P2P connection where BidMachine acts as payment aggregation agent.
                    example: false
                  bidder_id:
                    type: integer
                    description: Bidder ID.
                    example: 456
                  publisher_id:
                    type: integer
                    example: 33
                  source_id:
                    type: integer
                    example: 33
                  seat_id:
                    type: string
                    description: Buyer seat the bid was bought on, as sent by the bidder.
                    example: seat-42
                  adomain:
                    type: string
                    description: Primary advertiser domain of the winning creative.
                    example: example.com
                  country:
                    type: string
                    example: US
                  app_bundle:
                    type: string
                    example: com.some.app
                  platform:
                    type: string
                    example: ios
                  ad_type:
                    type: string
                    example: banner
                  impressions:
                    type: integer
                    example: 153
                  clicks:
                    type: integer
                    example: 0
                  ctr:
                    type: number
                    format: float
                    example: 0.07
                  spend:
                    type: number
                    format: float
                    example: 575.75
                  p2p_paas_fee:
                    type: number
                    format: float
                    description: PaaS fee the demand partner pays to BidMachine, in USD.
                    example: 12.5
                  seller_income:
                    type: number
                    format: float
                    example: 457.54
                  bidder_endpoint:
                    type: string
                    description: Current bidder endpoint URL from configuration.
                    example: https://dsp.example.com/rtb/bid
              example: '{"date":"2026-01-07","agency_id":283,"publisher_id":33,"source_id":33,"app_bundle":"com.some.app","impressions":153,"clicks":0,"seller_income":0.08}

                {"date":"2026-01-07","agency_id":283,"publisher_id":33,"source_id":33,"app_bundle":"1452992954","impressions":1750590,"clicks":686,"seller_income":382.69}

                {"date":"2026-01-07","agency_id":283,"publisher_id":33,"source_id":33,"app_bundle":"1471967529","impressions":92592,"clicks":80,"seller_income":35.89}

                '
            text/csv:
              schema:
                type: string
              example: '"2026-01-07",283,33,33,"com.some.app",153,0,0.08

                "2026-01-07",283,33,33,"1452992954",1750590,686,382.69

                "2026-01-07",283,33,33,"1471967529",92592,80,35.89

                "2026-01-07",283,33,33,"com.some.app",119552,161,30.95

                "2026-01-07",299,126,136,"com.some.app",118,14,0.49

                "2026-01-07",299,126,136,"1532397340",165290,90,34.67

                "2026-01-07",299,126,136,"6464458481",40787,75,11.9

                "2026-01-07",299,126,136,"6451130237",18831,37,5.07

                "2026-01-08",283,33,33,"1454398991",9002,6,3.94

                "2026-01-08",283,33,33,"com.some.app",20483,52,7.23

                "2026-01-08",299,126,136,"1532397340",161531,95,33.79

                "2026-01-08",299,126,136,"com.other.app",44055,104,16.24

                '
        '400':
          description: Bad Request – missing or invalid parameters.
        '401':
          description: Unauthorized – invalid or missing authentication credentials.
        '429':
          description: Too Many Requests – rate limit exceeded.
          headers:
            ad-exchange-warn-message:
              schema:
                type: string
              description: Rate limit warning message.
              example: You've been requesting too much. Please try again in 5 seconds.
      security:
      - basicAuth: []
  /report/p2p-revenue:
    get:
      operationId: retrieveP2pRevenueReportData
      summary: Retrieve P2P Revenue Report Data
      description: Returns P2P revenue reporting data in __NDJSON__ or __CSV__ format based on the query parameters. The endpoint accepts a date range, an optional output format, header preferences for CSV, and an optional list of fields (dimensions) to be returned. The maximum allowed time period for this report is **2 years**.
      tags:
      - Reporting
      parameters:
      - in: query
        name: start
        required: true
        schema:
          type: string
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
        description: Start date of the interval in `"yyyy-MM-dd"` format [inclusive].
      - in: query
        name: end
        required: true
        schema:
          type: string
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
        description: End date of the interval in `"yyyy-MM-dd"` format (exclusive).
      - in: query
        name: format
        required: false
        schema:
          type: string
          enum:
          - csv
          - json
        description: 'Response report format. Use `csv` for CSV output or `json` for newline-delimited JSON.

          '
      - in: query
        name: csv_header
        required: false
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
        description: 'Applicable only when format=csv. Use 0 for CSV without a header line or 1 for CSV with a header.

          '
      - in: query
        name: fields
        required: false
        schema:
          type: array
          items:
            type: string
          style: form
          explode: false
        description: 'Comma-separated list of dimensions and measures to include in the report. Possible values: `date`, `payer`, `is_paas`, `agency_id`, `agency_name`, `demand_partner`, `estimated_gross_spend`, `estimated_income`, `expected_payment`, `bm_fee`. When omitted, the report defaults to `date,payer,estimated_gross_spend,estimated_income,expected_payment,bm_fee` (split by payer).

          '
      responses:
        '200':
          description: Successful response with report data.
          content:
            application/x-ndjson:
              schema:
                type: object
                properties:
                  date:
                    type: string
                    format: date
                    example: '2026-03-01'
                  payer:
                    type: string
                    description: Who settles the money with the publisher - BidMachine, demand partner or Google.
                    example: bidmachine
                  is_paas:
                    type: boolean
                    description: P2P connection where BidMachine acts as payment aggregation agent.
                    example: true
                  agency_id:
                    type: integer
                    example: 283
                  agency_name:
                    type: string
                    example: Example Agency
                  demand_partner:
                    type: string
                    description: The demand partner behind the spend.
                    example: Magnite
                  estimated_gross_spend:
                    type: number
                    format: float
                    description: Estimated gross DSP API spend, in USD.
                    example: 575.75
                  estimated_income:
                    type: number
                    format: float
                    description: Estimated seller income, in USD.
                    example: 457.54
                  expected_payment:
                    type: number
                    format: float
                    description: 'Expected payment to the seller, in USD. For the DSP which pays on their numbers this equals the estimated income; for DSP which pays on BM numbers it is the BidMachine "seller income".

                      '
                    example: 457.54
                  bm_fee:
                    type: number
                    format: float
                    description: BidMachine fee, in USD.
                    example: 457.54
              example: '{"date":"2026-03-01","payer":"magnite","estimated_gross_spend":575.75,"estimated_income":457.54,"expected_payment":457.54,"bm_fee":457.54}

                {"date":"2026-03-01","payer":"nexxen","estimated_gross_spend":0.0,"estimated_income":212.3,"expected_payment":212.3,"bm_fee":0.0}

                {"date":"2026-03-01","payer":"bidmachine","estimated_gross_spend":1200.5,"estimated_income":980.1,"expected_payment":1010.0,"bm_fee":60.25}

                '
            text/csv:
              schema:
                type: string
              example: 'date,payer,estimated_gross_spend,estimated_income,expected_payment,bm_fee

                "2026-03-01","magnite",575.75,457.54,457.54,457.54

                "2026-03-01","nexxen",0.0,212.3,212.3,0.0

                "2026-03-01","bidmachine",1200.5,980.1,1010.0,60.25

                '
        '400':
          description: Bad Request – missing or invalid parameters.
        '401':
          description: Unauthorized – invalid or missing authentication credentials.
        '403':
          description: Forbidden – the account is not entitled to the P2P revenue report.
        '429':
          description: Too Many Requests – rate limit exceeded.
          headers:
            ad-exchange-warn-message:
              schema:
                type: string
              description: Rate limit warning message.
              example: You've been requesting too much. Please try again in 5 seconds.
      security:
      - basicAuth: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic