📚 Table of Contents

1. API Overview
2. Account Wide Reporting
- 2.1 Demand
3. Pagination
4. Error Handling

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 100 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 Demand

2.1.1 Demand Endpoint

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

curl "https://api-reporting.verve.com/brand/demand?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/demand?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/demand?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/demand?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=interstitial"

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

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

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

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

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

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

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

2.1.2 Request Parameter

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` (default: `json`)
`page`	Optional	The page number to return	For details, see the Pagination Parameter table
`page_size`	Optional	The number of records returned per page	For details, see the Pagination Parameter table
`group_by`	Optional	One or more dimensions, separated by commas	date, ad_format, app_bundle, app_site_domain, country_code, interstitial, platform, rewarded. For description of Available Dimension, see the table below.

2.1.3 Available Dimension

Dimension	Type	Description	Example
date	date	Report date in YYYY-MM-DD	2025-10-25
ad_format	string	Demand ad type	banner, video, native
app_bundle	string	Demand app bundle identifier	com.app.name
app_site_domain	string	App bundle or site domain	site.com
country_code	string	Country code in ISO 3166-1 alpha-3 format	USA
interstitial	integer	Whether the ad is interstitial	0 / 1
platform	string	Placement platform	Mobile Web, Desktop Web, Mobile In-App, CTV, Other, Unknown
rewarded	boolean	Whether placement is rewarded	true, false

2.1.4 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",
      "gross_revenue": 34917.81,
      "impressions": 109068916,
      "bids": 1219382746,
      "clicks": 290310,
      "dsp_requests": 41194680402,
      "wins": 766472694
    },
    {
      "date": "2025-10-19",
      "gross_revenue": 37153.63,
      "impressions": 123576875,
      "bids": 1527633303,
      "clicks": 305097,
      "dsp_requests": 48486533390,
      "wins": 897476730
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "ad_format": "video",
      "gross_revenue": 7398.540000000003,
      "impressions": 3053802,
      "bids": 154171659,
      "clicks": 159738,
      "dsp_requests": 7078824889,
      "wins": 102345821
    },
    {
      "ad_format": "banner",
      "gross_revenue": 59847.009999999944,
      "impressions": 217488293,
      "bids": 2427155781,
      "clicks": 280802,
      "dsp_requests": 59587126712,
      "wins": 1449152786
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "app_bundle": "1340929016",
      "gross_revenue": 0,
      "impressions": 0,
      "bids": 72,
      "clicks": 0,
      "dsp_requests": 15364,
      "wins": 69
    },
    {
      "app_bundle": "com.changdu.portugalreader",
      "gross_revenue": 0.01,
      "impressions": 10,
      "bids": 1276,
      "clicks": 0,
      "dsp_requests": 51676,
      "wins": 1083
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "country_code": "COL",
      "gross_revenue": 975.3900000000002,
      "impressions": 3076696,
      "bids": 33296219,
      "clicks": 29027,
      "dsp_requests": 1276294300,
      "wins": 24105888
    },
    {
      "country_code": "DOM",
      "gross_revenue": 19.689999999999984,
      "impressions": 89455,
      "bids": 958441,
      "clicks": 1431,
      "dsp_requests": 74110892,
      "wins": 802546
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "interstitial": 0,
      "gross_revenue": 52412.57999999995,
      "impressions": 224079801,
      "bids": 2238973787,
      "clicks": 282411,
      "dsp_requests": 73726818295,
      "wins": 1328186390
    },
    {
      "interstitial": 1,
      "gross_revenue": 19658.850000000002,
      "impressions": 8565990,
      "bids": 508042262,
      "clicks": 312996,
      "dsp_requests": 15954395497,
      "wins": 335763034
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "platform": "Mobile In-App",
      "gross_revenue": 44654.30999999996,
      "impressions": 121095782,
      "bids": 1749677268,
      "clicks": 520798,
      "dsp_requests": 49712435545,
      "wins": 1210391322
    },
    {
      "platform": "Mobile In-App",
      "gross_revenue": 820.6799999999995,
      "impressions": 105544,
      "bids": 791971,
      "clicks": 0,
      "dsp_requests": 3338931041,
      "wins": 708217
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "rewarded": false,
      "gross_revenue": 69748.43999999987,
      "impressions": 231387939,
      "bids": 2687525812,
      "clicks": 551728,
      "dsp_requests": 87477390660,
      "wins": 1618917241
    },
    {
      "rewarded": true,
      "gross_revenue": 2323.0099999999998,
      "impressions": 1257852,
      "bids": 59490237,
      "clicks": 43679,
      "dsp_requests": 2203823132,
      "wins": 45032183
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "date": "2025-10-29",
      "gross_revenue": 0,
      "impressions": 1,
      "bids": 58,
      "clicks": 0,
      "dsp_requests": 46018,
      "wins": 39
    },
    {
      "date": "2025-10-28",
      "gross_revenue": 0,
      "impressions": 0,
      "bids": 65,
      "clicks": 0,
      "dsp_requests": 19783,
      "wins": 57
    }
  ],
  "result_count": 2
}

{
  "status": "success",
  "data": [
    {
      "app_bundle": "com.vizorinteractive.zombiesettlersv2",
      "ad_format": "video",
      "country_code": "USA",
      "interstitial": 1,
      "platform": "Android",
      "app_site_domain": null,
      "rewarded": true,
      "gross_revenue": 0,
      "impressions": 0,
      "bids": 4,
      "clicks": 0,
      "dsp_requests": 3015,
      "wins": 4
    },
    {
      "app_bundle": "1525770311",
      "ad_format": "native",
      "country_code": "AUS",
      "interstitial": 0,
      "platform": "iOS",
      "app_site_domain": null,
      "rewarded": false,
      "gross_revenue": 0,
      "impressions": 0,
      "bids": 1,
      "clicks": 0,
      "dsp_requests": 2150,
      "wins": 0
    }
  ],
  "result_count": 2
}

country_code,gross_revenue,impressions,bids,clicks,dsp_requests,wins THA,600.99,1733711,23467904,3712,786840719,16756358 MLI,0.53,12588,70426,372,14913578,68997 GIB,0.00,2,6,0,375628,2 MSR,0,0,20,0,61940,19

date,platform,app_bundle,ad_format,country_code,interstitial,app_site_domain,rewarded,gross_revenue,impressions,clicks,wins
2026-03-30,CTV,112552,video,USA,1,,false,0,0,0,10
2026-03-30,CTV,com.doapps.android.mln.MLN_1e913e1b06ead0b66e30b6867bf63549,,USA,1,,false,0,0,0,0
2026-03-30,CTV,B08XY5ZBMV,,USA,1,,false,0,0,0,0
2026-03-30,CTV,com.graytv.android.kwtxnews,,USA,1,,false,0,0,0,0
2026-03-30,CTV,com.comcast.drewdirksen,,USA,1,,false,0,0,0,0
2026-03-30,CTV,B09G4Q6FT2,,USA,1,,false,0,0,0,0

{
  "status": "success",
  "data": [
    {
      "date": "2026-03-30",
      "platform": "Android",
      "app_bundle": "12716",
      "ad_format": null,
      "country_code": "USA",
      "interstitial": 1,
      "app_site_domain": null,
      "rewarded": false,
      "gross_revenue": 0,
      "impressions": 0,
      "clicks": 0,
      "wins": 0
    },
    {
      "date": "2026-03-30",
      "platform": "Android",
      "app_bundle": "B07HJC8G54",
      "ad_format": null,
      "country_code": "USA",
      "interstitial": 1,
      "app_site_domain": null,
      "rewarded": false,
      "gross_revenue": 0,
      "impressions": 0,
      "clicks": 0,
      "wins": 0
    }
  ],
  "result_count": 46000,
  "pagination": {
    "page": 1,
    "page_size": 46000,
    "total_rows": 118098,
    "total_pages": 3,
    "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 Parameter

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 Parameter 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 with change 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/demand?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=date,ad_format,app_bundle, app_site_domain&format=json&page=1&page_size=10000"

{
  "status":"success",
  "data":[
    {
      "date":"2026-04-23",
      "ad_format":null,
      "app_bundle":null,
      "app_site_domain":null,
      "gross_revenue":0,
      "impressions":0,
      "clicks":0,
      "wins":0
    },
    {
      "date":"2026-04-23",
      "ad_format":null,
      "app_bundle":"1016538839",
      "app_site_domain":null,
      "gross_revenue":0,
      "impressions":0,
      "clicks":0,
      "wins":0
    }
  ],
  "result_count":10000,
  "pagination":{
    "page":1,
    "page_size":10000,
    "total_rows":37985,
    "total_pages":4,
    "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/demand?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&group_by=date,ad_format,app_bundle, app_site_domain&format=json&page=2&page_size=10000"

{
  "status":"success",
  "data":[
    {
      "date":"2026-04-17",
      "ad_format":"video",
      "app_bundle":"com.xxxx.hisense",
      "app_site_domain":null,
      "gross_revenue":0,
      "impressions":0,
      "clicks":0,
      "wins":0
    },
    {
      "date":"2026-04-17",
      "ad_format":"video",
      "app_bundle":"com.xxxx.streambox",
      "app_site_domain":null,
      "gross_revenue":0,
      "impressions":0,
      "clicks":0,
      "wins":0
    }
  ],
  "result_count":10000,
  "pagination":{
    "page":2,
    "page_size":10000,
    "total_rows":37985,
    "total_pages":4,
    "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/demand?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date=2026-01-01&end_date=2026-01-31"

{
  "status":"success",
  "data":[
    {
      "date":"2026-04-23",
      "gross_revenue":61.146815019999956,
      "impressions":21790,
      "bids":127465,
      "clicks":0,
      "dsp_requests":351616409,
      "wins":122765
    },
    {
      "date":"2026-04-22",
      "gross_revenue":64.88060234,
      "impressions":26325,
      "bids":160707,
      "clicks":0,
      "dsp_requests":405317432,
      "wins":157565
    }
  ],
  "result_count":42,
  "pagination":{
    "page":1,
    "page_size":10000,
    "total_rows":42,
    "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/demand?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date=2026-01-01&end_date=2026-01-31&page=3&page_size=5000"

{
  "status":"success",
  "data":[
    {
      "date":"2026-04-23",
      "gross_revenue":61.146815019999956,
      "impressions":21790,
      "bids":127465,
      "clicks":0,
      "dsp_requests":351616409,
      "wins":122765
    },
    {
      "date":"2026-04-22",
      "gross_revenue":64.88060234,
      "impressions":26325,
      "bids":160707,
      "clicks":0,
      "dsp_requests":405317432,
      "wins":157565
    }
  ],
  "result_count":42,
  "pagination":{
    "page":1,
    "page_size":5000,
    "total_rows":42,
    "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/test/demand?account_auth_token={ACCOUNT_TOKEN}&start_date=2025-12-13&end_date=2026-04-22&group_by=date,platform,app_bundle,ad_format,country_code,interstitial,app_site_domain,rewarded&format=json&page=1&page_size=25000"

{
  "status":"success",
  "data":[
    {
      "date":"2026-03-30",
      "platform":"Android",
      "app_bundle":"12716",
      "ad_format":null,
      "country_code":"USA",
      "interstitial":1,
      "app_site_domain":null,
      "rewarded":false,
      "gross_revenue":0,
      "impressions":0,
      "clicks":0,
      "wins":0
    }
  ],
  "result_count":25000,
  "pagination":{
    "page":1,
    "page_size":25000,
    "total_rows":112155,
    "total_pages":5,
    "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/test/demand?account_auth_token={ACCOUNT_AUTH_TOKEN}&start_date=2025-12-13&end_date=2026-04-30&group_by=date,platform,app_bundle,ad_format,country_code,interstitial,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 270s 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 the Available Dimension table
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