Menu

Advanced Report

Note: Please be familiar with the API signature mechanism before accessing the API (refer to the API authentication description), that is, the source of some HTTP request headers in the API request sample.

1.Request URL

https://openapi.hyperbid.com/v1/report/full

Pre-Usage Instructions：

  1. After applying for report API access permission, you need to wait about 2 to 3 hours before data can be obtained. Otherwise, the data list will be empty, please wait patiently.
     
    How to verify permissions: Log in to the HyperBid backend, go to Account Info - API Key on the left sidebar. If the global Publisher Key is displayed, the permission is enabled. If not, contact HyperBid operation staff to apply for access.
     
  2. After data access is available, you can only query data starting from 10 days prior to the permission activation date.
     
    Example: If permission is activated on Feb 24, you can only obtain data from Feb 14 and later.
     
  3. Historical data will not be updated unless incomplete data is re-synced manually.
     
  4. Real-time HyperBid internal statistics data (impressions, clicks, etc.) is updated every 10 minutes, consistent with backend update frequency with minor possible delays.
     
  5. Yesterday’s third-party data including third-party revenue and impressions is updated every 2 hours, with a delay of 2 to 3 hours compared with developer backend.
     
    Example: Complete third-party revenue is available at 9:00 in developer backend, while OpenAPI may synchronize it around 12:00.

Usage Notes：

  1. If group_by contains any of segment_id, channel, sdk_version, app_version, user_type, idfa, the following metrics cannot be queried:
     
    unit_request, unit_filled_rate, unit_impression, unit_click, unit_ctr, unit_ecpm, unit_revenue, revenue_gap, ecpm_gap, impression_gap, click_gap
     
  2. Query dau_launch
     
    Restrictions: group_by cannot include placement_id, segment_id, nw_firm_id, format, unit_id, sdk_version, app_version; unit_id_list and placement_id_list must be empty.
     
  3. Query dau, estimated_revenue_arpu, engaged_rate, aipau
     
    Restrictions: group_by cannot include nw_firm_id, unit_id; unit_id_list must be empty.
     
  4. Query new_user, new_user_rate
     
    Restrictions: group_by only supports date_time, app_id, geo_short, channel; unit_id_list, placement_id_list, nw_firm_id_list must all be empty. New and old user data is available on T+1 day.
     
  5. Query load, load_filled_rate
     
    Restrictions: group_by cannot include nw_firm_id, unit_id, mm_firm_id; unit_id_list must be empty.
     
  6. Query request, request_filled_rate
     
    Restrictions: group_by cannot include nw_firm_id.
     
  7. Query bid_total, bid_request_rate, bid_win_rate, bid_ecpm
     
    Restrictions: group_by cannot include nw_firm_id. Additionally, bid_win_rate requires group_by to exclude placement_id and unit_id.

Usage Tips：

  1. Obtain data of multiple apps: pass multiple app_id values and group data by app.
  2. Obtain multi-day data: set start date and end date, group data by date_time. Since data updates infrequently and historical data is fixed, it is recommended to synchronize data of the latest 2 days daily.
  3. Data aggregation: pull detailed data with finest granularity grouping, then perform sum calculation locally.

2.Request method

POST

3.Request Parameters

param type required note sample

time_zone

String

 Y Timezone, enumeration value: UTC-8, UTC+8, UTC+0  "UTC+8"

start_date

Int

 Y Start date, format: YYYYmmdd 20250801

end_date

Int

 Y End date, format: YYYYmmdd 20250801

app_id_list

Array[String]

 N

A list of multiple Mediation Application IDs in the developer backend, maximum query 100

 ["ja547b671dc3ef29"]

placement_id_list

Array[String]

 N

A list of multiple Mediation Unit IDs in the developer backend, maximum query 100

  ["kde0e6953d508fee"]

segment_id_list

Array[Int]

 N

A list of multiple Traffic Group IDs in the developer backend, maximum query 100

 [300000126]

unit_id_list

Array[Int]

 N

A list of multiple Ad Unit IDs in the developer backend, maximum query 100

 [300000268]

abtest_item_id_list

Array[Int]

 N

A list of multiple A/B Test Item IDs in the developer backend, maximum query 100

 [300000025]

channel_list

Array[Int]

 N

A list of multiple Channel Names in the developer backend, maximum query 100

 ["MyChannel"]

geo_short_list

Array[String]

 N

Country short code list, default is all countries, maximum query 100

 ["US","CN"]

nw_firm_id_list

Array[Int]

 N

Network firm id list

 [1,2]

mm_firm_id_list

Array[Int]

 N

Mediation firm id list

 [1,2]

format_list

Array[Int]

 N

Ad Format list, enumeration value:
0: Native
1: Rewarded Video
2: Banner
3: Interstitial
4: Splash

 [0,1,2]

sdk_version_list

Array[String]

 N

SDK version list, maximum query 100

 ["1.0.0"]

app_version_list

Array[String]

 N

Application version list, maximum query 100

 ["5.0.0"]

platform_list

Array[Int]

 N

System platform list, enumeration value:

1: Android
2: iOS

 [1,2]

idfa_status_list

Array[Int]

 N

IDFA status list, enumeration value:

1: With IDFA
0: Without IDFA

 [1]

user_type_list

Array[Int]

 N

User type list, enumeration value:

1: New user
2: Retained user

 [1]

is_ps

Int

 N SDK Preset Strategy, enumeration value:
1：Yes
2：No		 2

metric

Array[String]

 N

When both “all” and other metrics are selected, all metrics are returned:

default (Default Metrics: dau, aipau, engaged_rate, estimated_revenue, estimated_revenue_ecpm, estimated_revenue_arpu, load, load_filled_rate, request, request_filled_rate,

impression, impression_rate, click, ctr),
all (All metrics),
dau (DAU),

dau_launch (Launch DAU),

deu (DEU),

engaged_rate (Engaged Rate),

aipau (Imp. /DAU),

aipu (Imp. /DEU),

new_user (New Users),

new_user_rate (New Users/DAU),

estimated_revenue (Estimated Revenue),

estimated_revenue_arpu (Estimated ARPDAU),

estimated_revenue_ecpm (Est. eCPM),

estimated_revenue_rate (Estimated Revenue Proportion),

bid_total (Participation in Price Comparison),

bid_request_rate (Price Comparison Participation Rate),

bid_win_rate (Price Comparison Winning Rate),

bid_ecpm (Price Comparison eCPM),

bid_win (Victory In Price Comparison),

load (Mediation Unit Requests),

load_filled_rate (Mediation Unit Request Fill Rate),

request (Ad Unit Attempt),

request_filled_rate (Ad Unit Attempt Fill Rate),

impression (Impression),

impression_rate (Impression Rate),

click (Click),

ctr (Click Rate),

request_cost_time (Latency),

sdk_impression_rate (Impression Proportion),

click_rate (Click Proportion),

ready_request (isReady),

ready_success_rate (isReady Rate),

revenue_gap (Revenue Gap),

ecpm_gap (eCPM Gap),

impression_gap (Impression Gap),

click_gap (Click Gap),

unit_request (Attempt API),

unit_filled_rate (Attempt Fill Rate API),

unit_impression (Impression API),

unit_click (Click API),

unit_ctr (CTR API),

unit_impression_rate (Impression API Proportion),

unit_click_rate (Click API Proportion),

arpu (ARPDAU API),

unit_revenue (Revenue API),

unit_ecpm (eCPM API),

unit_revenue_rate (Revenue API Proportion)

 ["dau","deu"]

group_by

Array[String]

 N

Filter dimension list. The supported dimensions are as follows:

date_time (Date, default),

app_id (Application),

placement_id (Mediation Unit),

segment_id (Traffic Group),

unit_id (Ad Unit),

abtest_item_id (A/B Test Item),

format (Ad Format),

nw_firm_id (Network Firm),

mm_firm_id (Mediation Firm),

geo_short (Country),

channel (Channel),

sdk_version(SDK Version),

app_version(Application Version),

idfa (IDFA Status),

platform (System Platform),

user_type (User Type)

 ["date_time","user_type"]

order_by

Array[Array[String][2]]

 N

Metric sorting, supports the following metrics:

request, impression, click, dau, deu, estimated_revenue, unit_request, unit_impression, unit_click, unit_revenue, load, new_user, dau_launch, request_filled_rate, load_filled_rate, ctr, ecpm, new_user_rate, arpu, engaged_rate, aipu, aipau, unit_filled_rate, impression_rate, unit_ctr, unit_ecpm, unit_ecpr, impression_gap, click_gap, estimated_revenue_ecpm, ready_success_rate, estimated_revenue_arpu, revenue_gap, ecpm_gap, request_cost_time, bid_request_rate, bid_total, impression_rate, bid_ecpm, bid_win, unit_revenue_rate, unit_impression_rate, unit_click_rate, sdk_impression_rate, click_rate, estimated_revenue_rate, ready_request

Supported sorting methods:

asc (Ascending order)

desc (Descending order)

 [["dau","desc"]]
start Int N The offset number indicates the starting point of the data. The default value is 0. 0
limit Int N The maximum number of data to be pulled each time, the default is 1000, optional [1,1000] 10

4.Return Parameters

param type required note
records Array[Object] N Record, object array. The structure of each record is shown in the records element structure below. It is empty when there is no data.
count Int N Total number of entries, empty if no data is availabletime_zone
time_zone String N Time zone, enumeration value: UTC-8, UTC+8, UTC+0
currency String N The currency of the developer account

The records element structure is as follows:

param type required note
date_time String N Date, format: YYYYmmdd. Only returned if date_time is selected in group_by
app_id String N The Application ID of the developer backend. This is returned only when the app_id dimension is selected in group_by.
app Object N
{
                "id": "ja57e2236063f468",
                "name": "CLS Smart Clean Master",
                "platform": "1",
                "pkg_name": "com.cls.smart.clean"
  }
Application  Info
placement_id String N

The Mediation Unit ID of the developer backend. This is returned only when the placement_id dimension is selected in group_by.
placement Object N
{
                "id": "k2aeb263e66fd008",
                "name": "CLS_RV14"
 }

Mediation Unit Info
segment_id Int N

The Traffic Group ID of the developer backend. This is returned only when the segment_id dimension is selected in group_by.
segment_name String N

Traffic Group name
unit_id Int N

The Ad Unit ID of the developer backend. This is returned only when the unit_id dimension is selected in group_by.
unit_name String N

Ad Unit name
abtest_item_id Int N

The A/B Test Item ID of the developer backend. This is returned only when the abtest_item_id dimension is selected in group_by.
abtest_item_name String N

abtest_item name
format Int N Ad format, group_by returns only when the format dimension is selected. Enumeration values:
0: Native
1: Rewarded Video
2: Banner
3: Interstitial
4: Splash
geo_short String N Country code. Returned only when geo_short dimension is selected in group_by
mm_firm_id Int N Mediation Platform ID. This is returned only when the mm_firm_id dimension is selected in group_by.
mm_firm_name String N Mediation Platform Name
nw_firm_id Int N Network ID. This is returned only when the nw_firm_id dimension is selected in group_by.
platform Int N

System Platform. This is returned only when the platform dimension is selected in group_by. Enumeration values:

1: Android
2: iOS
sdk_version String N

SDK Version. This is returned only when the sdk_version dimension is selected in group_by.
app_version String N

Application Version. This is returned only when the app_version dimension is selected in group_by.
channel String N

Channel. This is returned only when the channel dimension is selected in group_by.
idfa_status Int N

IDFA Status. This is returned only when the idfa dimension is selected in group_by. Enumeration value:

1: With IDFA
0: Without IDFA
user_type Int N

User Type.  This is returned only when the user_type dimension is selected in group_by. Enumeration value:

1: New user
2: Retained user
dau Int N DAU. Note: If some group_by dimensions (e.g. is_ps) are selected, DAU metric will not be returned in the response.
dau_launch Int N

Launch DAU. Note: If some group_by dimensions (e.g. segment_id, unit_id, nw_firm_id, format, sdk_version, app_version) are selected, this metric will not be returned in the response.
deu Int N DEU. Note: If some group_by dimensions (e.g. is_ps) are selected, DEU metric will not be returned in the response.
engaged_rate Float N

Engaged Rate
aipau Float N Imp. /DAU
aipu Float N Imp. /DEU
new_user Int N

New Users. Note: If some group_by dimensions (e.g. segment_id, unit_id, nw_firm_id, format, sdk_version, app_version, idfa) are selected, this metric will not be returned in the response.
new_user_rate Float N

New Users/DAU
estimated_revenue Float N

Estimate Revenue. The estimate revenue, returned according to the developer account currency
estimated_revenue_arpu Float N

Estimate ARPDAU, this item is returned only if there is dau
Unit: based on the developer account currency
estimated_revenue_ecpm Float N

Estimate eCPM
estimated_revenue_rate Float N

Estimate Revenue Proportion
bid_total Int N

Participation in Price Comparison. Note: If some group_by dimensions (e.g. nw_firm_id) are selected, this metric will not be returned in the response.
bid_request_rate Float N

Price Comparison Participation Rate. Note: If some group_by dimensions (e.g. nw_firm_id) are selected, this metric will not be returned in the response.
bid_win_rate Float N

Price Comparison Winning Rate. Note: If some group_by dimensions (e.g. placement_id, unit_id) are selected, this metric will returned in the response.
bid_ecpm Float N

Price Comparison eCPM
bid_win Int N
Price Comparison Wins
load Int N

Mediation Unit Requests. Note: If some group_by dimensions (e.g. unit_id, nw_firm_id, mm_firm_id) are selected, this metric will not be returned in the response.
load_filled_rate Float N

Mediation Unit Request Fill Rate. Note: If some group_by dimensions (e.g. unit_id, nw_firm_id, mm_firm_id) are selected, this metric will not be returned in the response.
request Int N

Ad Unit Attempt. Note: If some group_by dimensions (e.g. nw_firm_id) are selected, this metric will not be returned in the response.
request_filled_rate Float N

Ad Unit Attempt Fill Rate. Note: If some group_by dimensions (e.g. nw_firm_id) are selected, this metric will not be returned in the response.
impression Int N Impression
impression_rate Float N Impression Rate
click Int N Click
ctr Float N Click Rate
request_cost_time Int N

Latency(ms.)
click_rate Float N

Click Proportion
sdk_impression_rate Float N

Impression Proportion
ready_request Int N

isReady. Note: If some group_by dimensions (e.g. unit_id, nw_firm_id, mm_firm_id) are selected, isReady metric will not be returned in the response.
ready_success_rate Float N isReady Rate.
revenue_gap Float N

Revenue Gap. Note: If some group_by dimensions (e.g. segment_id, channel, sdk_version, app_version, user_type, idfa, is_ps) are selected, Gap metric will not be returned in the response.
ecpm_gap Float N eCPM Gap
impression_gap Float N Impression Gap
click_gap Float N Click Gap
unit_request Int N

Attempts API. Note: If some group_by dimensions (e.g. segment_id, sdk_version, app_version, channel, idfa, user_type, is_ps) are selected, API metric will not be returned in the response.

Select the nw_firm_id dimension does not return this metric.
unit_filled_rate Float N

Attempts Fill Rate API. Note: Select the nw_firm_id dimension does not return this metric.
unit_impression Int N Impression API
unit_click Int N Click API
unit_ctr Float N Click Rate API
unit_click_rate Float N Click API Proportion
unit_impression_rate Float N Impression API Proportion
arpu Float N ARPDAU, Note: If some group_by dimensions (e.g. nw_firm_id) are selected, this metric will not be returned in the response.
unit_revenue Float N Revenue API
unit_ecpm Float N eCPM API
unit_revenue_rate Float N Revenue API Proportion

5.Examples

Request Sample:

curl --location --request POST 'https://openapi.hyperbid.com/v1/report/full' \
--header 'X-Up-Key: a5c20012d6964913dcea19dbb09243282518505c' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1754033553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "start_date": 20250801,
    "end_date": 20250801,
    "group_by":["date_time"],
    "start": 0,
    "limit": 30,
    "time_zone": "UTC+8",
    "app_id_list":["ja547b671dc3ef29"]
}'

Response Example:

{
    "count": 1,
    "time_zone": "UTC+8",
    "currency": "USD",
    "records": [
        {
            "date_time": 20250801,
            "dau": 279,
            "aipau": 1.2043,
            "engaged_rate": 0.301,
            "estimated_revenue": 0.608784,
            "estimated_revenue_ecpm": 1.81,
            "estimated_revenue_arpu": 0.0021,
            "load": 1817,
            "load_filled_rate": 0.3307,
            "request": 4529,
            "request_filled_rate": 0.2525,
            "impression": 336,
            "click": 53,
            "ctr": 0.1577
        }
    ]
}
Previous
Report API
Next
LTV Report
Last modified: 2026-05-21Powered by