Every API here is available over the APIs.io API and to AI agents over MCP.
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