Table of Contents

1. API Overview

The Reporting API provides secure, scalable, and programmatic access to daily aggregated reporting metrics for both Demand and Supply across Brand+ (B+) marketplace.
Its key features are:

RESTful HTTP endpoints
Provide pre-defined reports (Demand and Supply by default)
Apply custom queries with filters on dimensions
Daily-granularity data available for the current period + the last 4 months (rolling retention)
Data freshness: updated daily by 08:00 UTC; reporting data is available with a T-1 delay (i.e., complete data is typically available up to yesterday)
Rate limits enforced at 200 requests/hour per account (Demand and Supply)
Export report in JSON and CSV format
Pagination support for efficient large dataset retrieval

2. Account Wide Reporting

2.1 Supply

2.1.1 Supply Endpoint

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=b_publisher_id"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=app_bundle"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=ad_format"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=country_code"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=interstitial"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=os"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=platform"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=placement_id"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=rewarded"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&level=group"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=date,ad_format,country_code"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&format=csv"

curl "https://api-reporting.verve.com/brand/supply?start_date={START_DATE}&end_date={END_DATE}&account_auth_token={ACCOUNT_AUTH_TOKEN}&group_by=app_site_domain,rewarded&filters=os:iOS,placement_id:1&format=csv"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=date,b_publisher_id,app_bundle,ad_format,country_code,interstitial,os,platform,placement_id,app_site_domain,rewarded&format=csv&page={PAGE_NUMBER}&page_size={PAGE_SIZE}"

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=date,b_publisher_id,app_bundle,ad_format,country_code,interstitial,os,platform,placement_id,app_site_domain,rewarded&format=json&page={PAGE_NUMBER}&page_size={PAGE_SIZE}"

📘
Note:
Group-Level Reporting (Publisher Group Account): By default, reports return aggregated data for all accounts under the same Publisher Group level=group. The auth_token used determines which Publisher Group the data is pulled from. If you need to analyze performance per account, you can:

Split results using group_by=b_publisher_id to view metrics by individual publisher.

Filter results using filters=b_publisher_id:{PUBLISHER_ID} to retrieve data for a specific publisher.

Both options - grouped or per - publisher - are supported, depending on your reporting needs.

2.1.2 Request Parameters

Parameter	Required?	Description	Example
`account_auth_token`	Required	Reporting API access token (unique per account)	1001a00a1234ab1111ab12a1abc, 12312311a10000a1a123412345678abc1234
`start_date`	Required	Start date of the range (YYYY-MM-DD)	2025-10-09
`end_date`	Required	End date of the range (YYYY-MM-DD)	2025-10-10
`format`	Optional	Data format in which the API returns the report. Allowed values: json, csv	json (default)
`page`	Optional	The page number to return	For details, see Pagination Parameters
`page_size`	Optional	The number of records returned per page	For details, see Pagination Parameters
`group_by`	Optional	One or more dimensions (comma-separated)	`date`, `b_publisher_id`, `ad_format`, `app_bundle`, `app_site_domain`, `country_code`, `interstitial`, `platform, os`, `placement_id`, `rewarded` For description, see Available Dimensions below.

2.1.3 Available Dimensions

Field name	Type	Description	Example
`date`	string	Date	2025-10-21
`b_publisher_id`	integer	Publisher ID	1000000001
`ad_format`	string	Supply ad type	banner, video, native
`app_bundle`	string	App bundle identifier	com.app.name
`app_site_domain`	string	Domain of app or site	site.com
`country_code`	string	3-letter format (ISO 3166-1, e.g., USA)	USA
`interstitial`	int64	Whether ad is interstitial	0 / 1
`platform`	string	Platform	Mobile Web, Desktop Web, Mobile In-App, CTV, Other, Unknown
`os`	string	Operating system	Android, iOS
`placement_id`	string	Inventory or placement ID	123456789
`rewarded`	boolean	Whether the ad is rewarded	true, false

2.1.4 Available Metrics

Metric	Type	Description
`impressions`	integer	Number of impressions served.
`payout`	float	Total supply earnings
`clicks`	integer	Number of clicks recorded.
`filled_requests`	integer	Number of requests that resulted in an ad being served.
`requests`	integer	Number of ad requests received.
`supply_wins`	integer	Number of auctions won on the supply side.

2.1.5 Response Example

📘
Note:
The sample data array below is shortened for readability. Actual API responses return all rows for the requested page based on your query parameters, page, and page_size, up to the result_count value.

{
  "status": "success",
  "data": [
    {
      "date": "2025-10-20",
      "impressions": 15794995,
      "payout": 5887.942341819769,
      "clicks": 71218,
      "filled_requests": 85688200,
      "requests": 514558600,
      "supply_wins": 17775725
    },
    {
      "date": "2025-10-19",
      "impressions": 16433745,
      "payout": 4860.173476566033,
      "clicks": 61770,
      "filled_requests": 104821600,
      "requests": 561662400,
      "supply_wins": 19004547
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "b_publisher_id": 1000000001,
      "impressions": 1297756,
      "payout": 1383.6833560557122,
      "clicks": 54793,
      "requests": 1840111422650

    }
  ],
  "result_count": 1
}

{
  "status": "success",
  "data": [
    {
      "app_bundle": "com.peoplefun.blockscapes",
      "impressions": 187113,
      "payout": 17.3342,
      "clicks": 29,
      "requests": 701100
    },
    {
      "app_bundle": "6459582322",
      "impressions": 784,
      "payout": 0.07921,
      "clicks": 0,
      "requests": 636000
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "ad_format": "video",
      "impressions": 461968,
      "payout": 2500.828379437391,
      "clicks": 93641,
      "requests": 0
    },
    {
      "ad_format": "native",
      "impressions": 0,
      "payout": 0,
      "clicks": 0,
      "requests": 1840111422650
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "country_code": "TZA",
      "impressions": 49,
      "payout": 0.022388687000000004,
      "clicks": 1,
      "requests": 59613517800
    },
    {
      "country_code": "BIH",
      "impressions": 15,
      "payout": 0.00215708,
      "clicks": 0,
      "requests": 99842146200
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "interstitial": 0,
      "impressions": 30998038,
      "payout": 3883.881341515259,
      "clicks": 8674,
      "requests": 1134083287850
    },
    {
      "interstitial": 1,
      "impressions": 1230702,
      "payout": 6864.234476870555,
      "clicks": 124314,
      "requests": 706028134800
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "os": "Android",
      "impressions": 5285542,
      "payout": 6175.952165653822,
      "clicks": 81355,
      "requests": 1063964977100
    },
    {
      "os": "iOS",
      "impressions": 26943198,
      "payout": 4572.163652731982,
      "clicks": 51633,
      "requests": 115825000
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "platform": "Mobile In-App",
      "impressions": 5286326,
      "payout": 6176.031378995818,
      "clicks": 81355,
      "requests": 763080533550
    },
    {
      "platform": "Mobile In-App",
      "impressions": 26942414,
      "payout": 4572.084439389987,
      "clicks": 51633,
      "requests": 1077030889100
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "placement_id": 100090103,
      "impressions": 8,
      "payout": 0.017404099,
      "clicks": 5,
      "requests": 200
    },
    {
      "placement_id": 100280902,
      "impressions": 187106,
      "payout": 17.326856343531006,
      "clicks": 28,
      "requests": 6100
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "rewarded": true,
      "impressions": 24497,
      "payout": 151.5486560585091,
      "clicks": 4882,
      "requests": 1718073898500
    },
    {
      "rewarded": false,
      "impressions": 32204243,
      "payout": 10596.56716232729,
      "clicks": 128106,
      "requests": 122037524150
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "date": "2025-10-20",
      "impressions": 48291556,
      "payout": 9251.581178819762,
      "clicks": 75359,
      "filled_requests": 301326400,
      "requests": 1182780528,
      "supply_wins": 17775725
    },
    {
      "date": "2025-10-19",
      "impressions": 64656223,
      "payout": 10389.56768323902,
      "clicks": 66645,
      "filled_requests": 432764600,
      "requests": 1432834463,
      "supply_wins": 19004547
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "date": "2026-03-22",
      "ad_format": null,
      "country_code": "",
      "impressions": 0,
      "payout": 0,
      "clicks": 0,
      "requests": 53288400
    },
    {
      "date": "2026-03-22",
      "ad_format": null,
      "country_code": "ARE",
      "impressions": 0,
      "payout": 0,
      "clicks": 0,
      "requests": 153627000
    }
  ],
  "result_count": 2
}

date,impressions,payout,clicks,filled_requests,requests,supply_wins
2026-03-22,16301313,5709.14,33227,211201600,19172202800,24291587
2026-03-21,15861296,5554.16,35072,225928400,18028070850,23328551
2026-03-20,13779599,5555.52,28973,219974200,17564085200,21604191

app_site_domain,rewarded,impressions,payout,clicks,requests
,true,4336473,6879.11,250034,0
,false,777265550,170577.81,420337,0
,false,0,0,0,724369691800
,true,0,0,0,45842967200

date,b_publisher_id,app_bundle,ad_format,country_code,interstitial,os,platform,placement_id,app_site_domain,rewarded,impressions,payout,clicks,request
2026-03-22,1000000001,6740463410,,TUR,1,iOS,Mobile In-App,1,,false,0,0,0,0
2026-03-22,1000000001,com.demo.entertainment.app,banner,CAN,1,Android,Mobile In-App,1,,false,0,0,0,0
2026-03-22,1000000001,1425793208,,ARE,0,iOS,iOS,1,,false,0,0,0,0
2026-03-22,1000000001,com.example.game,,GBR,1,Android,Mobile In-App,1,,false,0,0,0,0
2026-03-22,1000000001,com.princess.com.example.game,,TUR,1,Android,Mobile In-App,1,,false,0,0,0,0

{
  "status": "success",
  "data": [
    {
      "date": "2026-03-22",
      "b_publisher_id": 1000000001,
      "app_bundle": null,
      "ad_format": null,
      "country_code": "ARE",
      "interstitial": 0,
      "os": "iOS",
      "platform": "Mobile In-App",
      "placement_id": 1,
      "app_site_domain": null,
      "rewarded": false,
      "impressions": 0,
      "payout": 0,
      "clicks": 0,
      "request": 0
    },
    {
      "date": "2026-03-22",
      "b_publisher_id": 1000000001,
      "app_bundle": null,
      "ad_format": null,
      "country_code": "ARE",
      "interstitial": 1,
      "os": "iOS",
      "platform": "Mobile In-App",
      "placement_id": 1,
      "app_site_domain": null,
      "rewarded": false,
      "impressions": 0,
      "payout": 0,
      "clicks": 0,
      "request": 0
    }
  ],
  "result_count": 10000,
  "pagination": {
    "page": 1,
    "page_size": 10000,
    "total_rows": 230699210,
    "total_pages": 23070,
    "has_more": true
  }
}

3. Pagination

Use Pagination when:

Your query returns more than 10,000 rows
You need to retrieve the complete dataset across multiple pages

3.1 Pagination Parameters

Parameter	Type	Default	Range	Description	Behaviour
`page`	integer	1	≥ 1	Page number to retrieve	Increment this value (page=1,2,3) to fetch subsequent result sets
`page_size`	integer	10,000	1-50,000	Number of records returned per page	The API supports up to 50,000 rows per page, depends on how many `group_by` dimensions are requested. If the response size exceeds 30 MB, the API returns HTTP `422` with a recommended `page_size` value, see Example: Handling page_size limit (422 error)

📘
Note:
See Request Parameters section for complete parameter details.

3.2 How Pagination Works

If the page parameter is not included, the API returns up to 10,000 rows by default
Use the page parameter to fetch additional data i.e. page = 1, page =2, page =3, etc.
Keep all query parameters consistent across requests changing only the page parameter

📘
Important Notes
⚠️ Default limit When the result set exceeds 10,000 rows, use pagination (page parameter) to retrieve the full dataset across pages. If the page parameter is not included, the response is limited to 10,000 rows. It is recommended to always include the page parameter.
Ordering behavior The Pagination API returns date in descending order (DESC) by default, ensuring that the most recent records appear first. This order ensures consistency and fetches the complete data across pages when using pagination

3.3 Pagination Example

📘
Note:
The sample data array below is shortened for readability. Actual paginated responses may include additional rows depending on page, page_size, and result_count.

Example: Retrieve data by Page = 1

Use this request to fetch the first set of results with a defined page size.

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date=2026-01-01&end_date=2026-04-22&group_by=date,b_publisher_id,app_bundle&format=json&page=1&page_size=10000"

{
  "status": "success",
  "data": [
    {
      "date": "2026-04-22",
      "b_publisher_id": 1100000000,
      "app_bundle": null,
      "impressions": 184,
      "payout": 0.28111381433700006,
      "clicks": 15,
      "requests": 46085800
    },
    {
      "date": "2026-04-22",
      "b_publisher_id": 1100000000,
      "app_bundle": "1000013295",
      "impressions": 0,
      "payout": 0,
      "clicks": 0,
      "requests": 0
    }
  ],
  "result_count": 10000,
  "pagination": {
    "page": 1,
    "page_size": 10000,
    "total_rows": 11229261,
    "total_pages": 1123,
    "has_more": true
  }
}

Example: Retrieve data by Page = 2

Use this request to fetch the next set of results by incrementing the page value.

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date=2026-01-01&end_date=2026-04-22&group_by=date,b_publisher_id,app_bundle&format=json&page=2&page_size=10000"

{
  "status": "success",
  "data": [
    {
      "date": "2026-04-22",
      "b_publisher_id": 1100000000,
      "app_bundle": "1634770185",
      "impressions": 0,
      "payout": 0,
      "clicks": 0,
      "requests": 1200
    },
    {
      "date": "2026-04-22",
      "b_publisher_id": 1100000000,
      "app_bundle": "1634782288",
      "impressions": 0,
      "payout": 0,
      "clicks": 0,
      "requests": 1200
    }
  ],
  "result_count": 10000,
  "pagination": {
    "page": 2,
    "page_size": 10000,
    "total_rows": 11229261,
    "total_pages": 1123,
    "has_more": true
  }
}

Example: Default request- first page, 10,000 rows

If page and page_size are not provided, the API returns up to 10,000 rows by default.

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date=2026-01-01&end_date=2026-01-31"

{
  "status":"success",
  "data":[
    {
      "date":"2026-04-23",
      "impressions":12775086,
      "payout":5982.207628514456,
      "clicks":19472,
      "filled_requests":127727200,
      "requests":14082457000,
      "supply_wins":29900004
    },
    {
      "date":"2026-04-22",
      "impressions":11845215,
      "payout":5721.721004888781,
      "clicks":26546,
      "filled_requests":133902200,
      "requests":14788054050,
      "supply_wins":29806114
    }
  ],
  "result_count":124,
  "pagination":{
    "page":1,
    "page_size":10000,
    "total_rows":124,
    "total_pages":1,
    "has_more":false
  }
}

Example: Specific page with custom page size

Use this request to fetch fewer records per page for easier handling.

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date=2026-01-01&end_date=2026-01-31&page=1&page_size=5000"

{
  "status":"success",
  "data":[
    {
      "date":"2026-04-23",
      "impressions":12775086,
      "payout":5982.207628514456,
      "clicks":19472,
      "filled_requests":127727200,
      "requests":14082457000,
      "supply_wins":29900004
    },
    {
      "date":"2026-04-22",
      "impressions":11845215,
      "payout":5721.721004888781,
      "clicks":26546,
      "filled_requests":133902200,
      "requests":14788054050,
      "supply_wins":29806114
    }
  ],
  "result_count":124,
  "pagination":{
    "page":1,
    "page_size":5000,
    "total_rows":124,
    "total_pages":1,
    "has_more":false
  }
}

Example: Wide query with reduced page size

For queries with multiple dimensions (wide dataset), reduce page_size to avoid large responses.

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date=2026-01-01&end_date=2026-04-23&group_by=date,b_publisher_id,app_bundle,ad_format,country_code,interstitial,os,platform,placement_id,app_site_domain,rewarded&page=1&page_size=25000"

{
  "status":"success",
  "data":[
    {
      "date":"2026-04-23",
      "b_publisher_id":1100000001,
      "app_bundle":null,
      "ad_format":null,
      "country_code":"",
      "interstitial":0,
      "os":"",
      "platform":"Mobile In-App",
      "placement_id":0,
      "app_site_domain":"",
      "rewarded":false,
      "impressions":0,
      "payout":0,
      "clicks":0,
      "requests":41712000
    },
    {
      "date":"2026-04-23",
      "b_publisher_id":1100000001,
      "app_bundle":null,
      "ad_format":null,
      "country_code":"",
      "interstitial":0,
      "os":"Android",
      "platform":"Mobile In-App",
      "placement_id":0,
      "app_site_domain":"",
      "rewarded":false,
      "impressions":0,
      "payout":0,
      "clicks":0,
      "requests":1200
    }
  ],
  "result_count":25000,
  "pagination":{
    "page":1,
    "page_size":25000,
    "total_rows":294767248,
    "total_pages":11791,
    "has_more":true
  }
}

Example: Handling page_size limit (422 error)

If the response size exceeds ~30MB, the API returns HTTP 422 (PAGE_SIZE_EXCEEDED), In such case, reduce the page_size as defined in Response.

curl "https://api-reporting.verve.com/brand/supply?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date=2025-12-13&end_date=2026-04-30&group_by=date,b_publisher_id,app_bundle,ad_format,country_code,interstitial,os,platform,placement_id,app_site_domain,rewarded&format=json&page=1&page_size=50000"

{
  "status": "error",
  "error": {
    "code": "PAGE_SIZE_EXCEEDED",
    "message": "The requested page_size (50000) exceeds the maximum returnable rows for this query. Only 46811 rows could be retrieved. Please set page_size to 46811 or lower."
  }
}

4. Error Handling

HTTP Status	Error Code	Cause	Fix
`422`	PAGE_SIZE_EXCEEDED	Requested `page_size` exceeds the safe limit for the query width	Reduce `page_size` to the value recommended in the error response
`503`	JOB_NOT_COMPLETE	First request for a new query exceeded the `270`s cold-start timeout	Retry the identical request after 15 seconds; the query result is cached and will return immediately
`429`	RATE_LIMIT_EXCEEDED	Exceeded `200` requests/hour or `5` requests/second	Wait and retry; check `Retry-After` header
`400`	MISSING_REQUIRED_PARAMS	`start_date` or `end_date` missing	Include both date parameters
`400`	INVALID_DATE_RANGE	`end_date` before `start_date` or range exceeds 4 months	Correct the date range
`400`	INVALID_CUSTOM_DIMENSIONS	Unsupported dimension in `group_by`	See Available Dimensions
`401`	INVALID_API_KEY	Token not found or not authorized for this endpoint	Verify your `account_auth_token`
`403`	ACCESS_DENIED	Token exists but not permitted for this business unit	Contact support