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 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 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` (default: `json`)
`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, separated by commas	`date`, `ad_format`, `app_bundle`, `app_site_domain`, `country_code`, `interstitial`, `platform`, `rewarded`. For details, see Available Dimensions

2.1.3 Available Dimensions

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 Available Metrics

Metric	Type	Description
`gross_revenue`	float	Total gross revenue.
`impressions`	integer	Number of impressions.
`bids`	integer	Number of bids received.
`clicks`	integer	Number of clicks.
`dsp_requests`	integer	Number of DSP requests.
`wins`	integer	Number of winning bids.

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",
      "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 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 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, and 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/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/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
`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`
`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
`429`	RATE_LIMIT_EXCEEDED	Exceeded 200 requests/hour or 5 requests/second	Wait and retry; check `Retry-After` header
`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