Menu

Waterfall API

1. Get Specify All Adsources Under Segment Group

Note: Retrieving adsources under segment currently running A/B Test is not supported. Attempting to do so will result in the error: {“errors”:“code: 4602, msg: the mediation connection not found”}. If required, please use API6 instead.

1.1 Request URL

https://api.toponad.net/v3/waterfall/:mediation_group_id/segment_id/:segment_id/units

1.2 Request method

GET

1.3 Request params

params type required notes
ecpm_currency String N eCPM currency unit, default USD when not transmitting, optional CNY

1.4 Return data

fields type required notes
offer_list_switch Int Y  
ecpm_currency String Y eCPM currency unit, corresponding to the parameter ecpm_currency when requesting, Returns the ecpm and auto_ecpm prices in the ad_source_list parameter based on the corresponding unit value of this field
parallel_request_number Int Y Parallel request number
offer_list Array[Object] Y My offer list in used
offer_list.offer_id String Y Offer id
offer_list.offer_name String Y Offer name
ad_source_list Array[Object] Y Adsources list in used
ad_source_list.ad_source_id Int Y Adsource ID
ad_source_list.name String Y Adsource name
ad_source_list.header_bidding_switch Int Y If support Header Bidding, The unit was identified when it was created
1: not support,
2: support
ad_source_list.ecpm String Y eCPM
ad_source_list.auto_ecpm_switch Int Y Automatically optimize the ECPM
1: not open auto eCPM sort switch, 2: open auto eCPM sort switch
ad_source_list.auto_ecpm String Y Auto eCPM
ad_source_list.hour_cap Int Y -1 : close
ad_source_list.day_cap Int Y -1 : close
ad_source_list.pacing Int Y -1 : close
free_ad_source_list Array[Object] Y Adsource list not in used
free_ad_source_list.ad_source_id Int Y Adsource ID
free_ad_source_list.name String Y Adsource name
free_ad_source_list.header_bidding_switch Int Y If support Header Bidding, The unit was identified when it was created
1: Not support
2: Support
free_ad_source_list.ecpm String Y eCPM
free_ad_source_list.auto_ecpm_switch Int Y Automatically optimize the ECPM
1: not open auto eCPM sort switch, 2: open auto eCPM sort switch
free_ad_source_list.auto_ecpm String Y Auto eCPM

1.5 Sample

Request address sample:

https://api.toponad.net/v3/waterfall/116112/segment_id/600262/units

Sample request parameter:

{
    "ecpm_currency" : "USD"
}

Return sample:

{
    "offer_list_switch": 2,
    "ecpm_currency": "USD",
    "parallel_request_number": 2,
    "offer_list": [],
    "ad_source_list": [
        {
            "ad_source_id": 681853,
            "name": "Chartboost_int_2",
            "header_bidding_switch": 1,
            "ecpm": "66",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0",
            "hour_cap": -1,
            "day_cap": -1,
            "pacing": -1
        },
        {
            "ad_source_id": 681852,
            "name": "Sigmob_int_2",
            "header_bidding_switch": 1,
            "ecpm": "20",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0",
            "hour_cap": 4,
            "day_cap": 5,
            "pacing": 6
        }
    ],
    "free_ad_source_list": [
        {
            "ad_source_id": 681851,
            "name": "Kuaishou Ads_int_2",
            "header_bidding_switch": 1,
            "ecpm": "50",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0"
        },
        {
            "ad_source_id": 681850,
            "name": "Mintegral_int_1",
            "header_bidding_switch": 1,
            "ecpm": "100",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0"
        },
        {
            "ad_source_id": 681854,
            "name": "Facebook_int_2",
            "header_bidding_switch": 1,
            "ecpm": "22",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0"
        }
    ]
}

2. Set Waterfall's Adsources(Expired, Please use API 5)

2.1 Request URL

https://api.toponad.net/v3/waterfall/:mediation_group_id/segment_id/:segment_id/units

2.2 Request method

PUT

2.3 Request params

params type required notes
parallel_request_number Int Y Parallel request number
offer_switch Int N Offer switch
ad_source_list Array[Object] Y Adsources need to binding
ad_source_list.ad_source_id Int Y Adsource ID
ad_source_list.header_bidding_switch Int N If support Header Bidding, The unit was identified when it was created
1: not support,
2: support
ad_source_list.ecpm String Y eCPM
ad_source_list.auto_ecpm_switch Int Y 1: not open auto eCPM sort switch
2: open auto eCPM sort switch
ad_source_list.hour_cap Int N Do not pass or pass -1 means unlimited
ad_source_list.day_cap Int N Do not pass or pass -1 means unlimited
ad_source_list.pacing Int N Do not pass or pass -1 means unlimited
unbind_ad_source_list Array[Int] N Unbind the adsource and send only the adsource id
ecpm_currency String N eCPM currency unit, corresponding to the parameter ecpm_currency when requesting, Returns the ecpm and auto_ecpm prices in the ad_source_list parameter based on the corresponding unit value of this field

2.4 Return data

fields type required notes
mediation_group_id Int Y Mediation Group ID
segment_id Int Y Segment ID

2.5 Sample

Request address sample:

https://api.toponad.net/v3/waterfall/116112/segment_id/600262/units

Sample request parameter:

{
    "parallel_request_number" : 1,
    "offer_switch" : 1,
    "ad_source_list": [
            {
                "ad_source_id": 681853,
                "name": "Chartboost_int_2",
                "header_bidding_switch": 1,
                "ecpm": "66",
                "auto_ecpm_switch": 1,
                "auto_ecpm": "0",
                "hour_cap": -1,
                "day_cap": -1,
                "pacing": -1
            },
            {
                "ad_source_id": 681852,
                "name": "Sigmob_int_2",
                "header_bidding_switch": 1,
                "ecpm": "20",
                "auto_ecpm_switch": 1,
                "auto_ecpm": "0",
                "hour_cap": 4,
                "day_cap": 5,
                "pacing": 6
            }
        ],
    "unbind_adsource_list" : [
        681851,
        681850,
        681854
    ]
}

Return sample:

{
    "mediation_group_id": 116112,
    "segment_id": 600262
}

3. Batch enable/disable Waterfall's Adsources

3.1 Request URL

https://api.toponad.net/v3/waterfall/units/status

3.2 Request method

GET

3.3 Request params

params type required notes
placement_id String Y Placement ID
mediation_group_id Int Y Mediation Group ID
segment_id Int Y Segment ID, where 0 represents the default group
abtest_group_item_id Int N Segment A/B Test Group ID: When no A/B Testis conducted for the segment, pass in 0 or leave it empty.
ad_source_ids Array[Int] Y Adsources ID List
status Int Y Operation Status, Note: When enabling or disabling an operation, the Adsource ID passed must be bound to a segment_id (i.e., only enabled or disabled for bound adources). Enumeration description:
1: Disable
3: Enable
11: Unbind

3.4 Return data

fields type required notes
items Array[Object] Y List of invalid adsource information. Note:
1. If the list is empty, the operation was successful.
2. If the list is not empty, it indicates which adsource failed validation. All adsources (including those that passed validation) failed the operation.
items.id Int Y Adsource ID
items.err_code Int Y Error Code
items.err_msg String Y Error messages, partial descriptions as follows: 1. “The unit is not yet bound to the segment”: When enabling or disabling operations, parameters contain unbound adsources.

3.5 Sample

Request address sample:

https://api.toponad.net/v3/waterfall/units/status

Sample request parameter:

{
    "placement_id" : "34343943uucce33",
    "mediation_group_id" : 100000,
    "segment_id" : 100000,
    "abtest_group_item_id": 0,
    "ad_source_ids": [232,435],
    "status": 1       
}

Return sample:

{
    "items": [
        {
            "id": 232,
            "err_code": 4000
            "err_msg": "the unit not found"
        }
    ]
}

4. Retrieve all Waterfall properties from the Adsources

Note: Segment currently running A/B Test. A single segment_id may correspond to multiple entries (associated with different test groups abtest_group_item_id).

4.1 Request URL

https://api.toponad.net/v3/waterfall/units

4.2 Request method

GET

4.3 Request params

params type required notes
ids Array[Int] Y Adsource ID List: Maximum quantity limit is 100, minimum quantity limit is 1.
currency String Y The currency units corresponding to ecpm, bid_floor, etc., can be set to USD or CNY.

4.4 Return data

fields type required notes
id Int Y Adsource ID
items Array[Object] Y List of all Waterfall information for adsource
items.mediation_group_id Int Y Mediation Group ID
items.segment_id Int Y Segment ID
items.abtest_group_item_id Int Y Segment A/B Test Group ID, where 0 indicates the current segment is not undergoing experimentation.
items.ecpm Double Y eCPM price, currency unit specified by the request parameter currency
items.ecpm_rank Int Y Adsource display priority at the same price, value range: [1,99], where a higher value indicates higher priority.
items.auto_ecpm_switch  Int  Y Enable automatic eCPM optimization
1: Disable
2: Enable
items.auto_ecpm Double Y Enable automatic eCPM optimization Automatic eCPM, where 0 indicates disabled
items.show_delay Int Y Delay show time, in milliseconds, range [5000]. Note: Only available for certain ad formats, such as interstitial ads. For non-interstitial ads or when not applicable, pass 0.
items.show_delay_rate Int Y Delayed show probability, range [1,100]. Note: Only available for certain formats, such as interstitial ads. For non-interstitial or non-display formats, pass 0.
items.bid_floor Double Y Bid Floor Price, currency unit specified by the request parameter ‘currency’. For non-bidding or no interest, pass 0.
items.setup_sw Int Y Adsource enabled for this segment. Enumeration description: 1: Yes 2: No
items.cap_hour Int Y Maximum show limit per hour. -1 indicates no restriction. Note: This attribute is only available for enabled adsource. Pass -1 when disabled.
items.cap_day Int Y Maximum show limit per day. -1 indicates no restriction. Note: This attribute is only available for enabled adsource. Pass -1 when disabled.
items.pacing Int Y Show interval, -1 indicates no restriction. Note: This property is only available for enabled adsource. Pass -1 when disabled.

4.5 Sample

Request address sample:

https://api.toponad.net/v3/waterfall/units?ids=417018,2280206&currency=CNY

Sample request parameter:

curl --location --request GET 'https://api.toponad.net/v3/waterfall/units?ids=417018,2280206&currency=CNY' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0===b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626056011000' \
--header 'Content-Type: application/json' \
--data-raw ''

Return sample:

[
    {
        "id": 2280206,
        "items": [
            {
                "mediation_group_id": 273234,
                "segment_id": 0,
                "abtest_group_item_id": 0,
                "ecpm": 2,
                "ecpm_rank": 1,
                "remark": "",
                "setup_sw": 1,
                "auto_ecpm_switch": 1,
                "auto_ecpm": 0,
                "cap_hour": -1,
                "cap_day": -1,
                "pacing": -1,
                "show_delay": 0,
                "show_delay_rate": 100,
                "bid_floor": 0
            }
        ]
    }
]

5. Edit (Bind + Enable) All Waterfall Properties for Adsources

5.1 Request URL

https://api.toponad.net/v3/waterfall/units

5.2 Request method

PUT

5.3 Request params

fields type required notes
placement_id String Y Placement ID
currency String Y The currency units corresponding to ecpm, bid_floor, etc., can be set to USD or CNY.
items Array[Object] Y List of all Waterfall information for multiple adsources. Note: If the default adsource is not yet bound to a segment_id, modify the property while simultaneously binding it to the segment.
items.id Int Y Adsource ID
items.items Array[Object] Y List of all Waterfall information under each Adsource ID
Note: Since these are identical attributes, items must either be modified together or left unchanged altogether.
items.items.mediation_group_id Int Y Mediation Group ID
items.items.segment_id Int Y Segment ID
items.items.abtest_group_item_id Int Y Segment A/B Test Group ID, where 0 indicates the current segment is not undergoing experimentation.
items.items.ecpm Double Y eCPM price, currency unit specified by the request parameter currency
items.items.ecpm_rank Int Y Adsource display priority at the same price, value range: [1,99], where a higher value indicates higher priority.
items.items.auto_ecpm_switch  Int  Y  Enable automatic eCPM optimization
1: Disable
2: Enable
items.items.show_delay Int Y Delay show time, in milliseconds, range [5000]. Note: Only available for certain ad formats, such as interstitial ads. For non-interstitial ads or when not applicable, pass 0.
items.items.show_delay_rate Int Y Delayed show probability, range [1,100]. Note: Only available for certain formats, such as interstitial ads. For non-interstitial or non-display formats, pass 0.
items.items.bid_floor Double Y Bid Floor Price, currency unit specified by the request parameter ‘currency’. For non-bidding or no interest, pass 0.
items.items.setup_sw Int Y Adsource enabled for this segment. Enumeration description: 1: Yes 2: No
items.items.cap_hour Int Y Maximum show limit per hour. -1 indicates no restriction. Note: This attribute is only available for enabled adsource. Pass -1 when disabled.
items.items.cap_day Int Y Maximum show limit per day. -1 indicates no restriction. Note: This attribute is only available for enabled adsource. Pass -1 when disabled.
items.items.pacing Int Y Show interval, -1 indicates no restriction. Note: This property is only available for enabled adsource. Pass -1 when disabled.

5.4 Return data

fields type required notes
items Array[Object] Y List of invalid adsource information. Note:
1. If the list is empty, the operation was successful.
2. If the list is not empty, it indicates which adsource failed validation. All adsources (including those that passed validation) failed the operation.
items.index Int Y The index of the item containing the error, starting from 0.
items.err_code Int Y Error Code
items.err_msg String Y Error Message

5.5 Sample

Request address sample:

https://api.toponad.net/v3/waterfall/units

Sample request parameter:

{
	"placement_id":"qdfji3434====",
	"currency":"USD",
	"items":[
		{
			"id": 2280206,
			"items": [
				{
					"mediation_group_id": 273234,
					"segment_id": 0,
					"abtest_group_item_id": 0,
					"ecpm": 2,
					"ecpm_rank": 1,
					"remark": "",
					"setup_sw": 1,
					"auto_ecpm_switch": 1,
					"auto_ecpm": 0,
					"cap_hour": -1,
					"cap_day": -1,
					"pacing": -1,
					"show_delay": 0,
					"show_delay_rate": 100,
					"bid_floor": 0
				}
			]
		}		
	]     
}

Return sample:

{
    "items": [
        {
            "index": 0,
            "err_code": 4602,
            "err_msg": "the mediation connection not found"
        }
    ]
}

6. Get all adsources under the specified segment's A/B Test Group

Note: When the specified segment is not running an A/B Test, pass 0 for `abtest_group_item_id`. If an A/B Test is active, pass the corresponding A/B Test Group ID. If the parameter is incorrect or the current segment is running an A/B Test but the passed test group ID is 0, an error will be returned: {“errors”:“code: 4602, msg: the mediation connection not found”}

6.1 Request URL

https://api.toponad.net/v3/waterfall/:mediation_group_id/segment_id/:segment_id/abtest_group_item_id/:abtest_group_item_id/units

6.2 Request method

GET

6.3 Request params

params type required notes
ecpm_currency String N eCPM currency unit, default USD when not transmitting, optional CNY

6.4 Return data

fields type required notes
offer_list_switch Int Y  
ecpm_currency String Y eCPM currency unit, corresponding to the parameter ecpm_currency when requesting, Returns the ecpm and auto_ecpm prices in the ad_source_list parameter based on the corresponding unit value of this field
parallel_request_number Int Y Parallel request number
offer_list Array[Object] Y My offer list in used
offer_list.offer_id String Y Offer id
offer_list.offer_name String Y Offer name
ad_source_list Array[Object] Y Adsources list in used
ad_source_list.ad_source_id Int Y Adsource ID
ad_source_list.name String Y Adsource name
ad_source_list.header_bidding_switch Int Y If support Header Bidding, The unit was identified when it was created
1: not support,
2: support
ad_source_list.ecpm String Y eCPM
ad_source_list.auto_ecpm_switch Int Y Automatically optimize the ECPM
1: not open auto eCPM sort switch, 2: open auto eCPM sort switch
ad_source_list.auto_ecpm String Y Auto eCPM
ad_source_list.hour_cap Int Y -1 : close
ad_source_list.day_cap Int Y -1 : close
ad_source_list.pacing Int Y -1 : close
free_ad_source_list Array[Object] Y Adsource list not in used
free_ad_source_list.ad_source_id Int Y Adsource ID
free_ad_source_list.name String Y Adsource name
free_ad_source_list.header_bidding_switch Int Y If support Header Bidding, The unit was identified when it was created
1: Not support
2: Support
free_ad_source_list.ecpm String Y eCPM
free_ad_source_list.auto_ecpm_switch Int Y Automatically optimize the ECPM
1: not open auto eCPM sort switch, 2: open auto eCPM sort switch
free_ad_source_list.auto_ecpm String Y Auto eCPM

6.5 Sample

Request address sample:

https://api.toponad.net/v3/waterfall/116112/segment_id/600262/abtest_group_item_id/0/units

Sample request parameter:

{
    "ecpm_currency" : "USD"
}

Return sample:

{
    "offer_list_switch": 2,
    "ecpm_currency": "USD",
    "parallel_request_number": 2,
    "offer_list": [],
    "ad_source_list": [
        {
            "ad_source_id": 681853,
            "name": "Chartboost_int_2",
            "header_bidding_switch": 1,
            "ecpm": "66",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0",
            "hour_cap": -1,
            "day_cap": -1,
            "pacing": -1
        },
        {
            "ad_source_id": 681852,
            "name": "Sigmob_int_2",
            "header_bidding_switch": 1,
            "ecpm": "20",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0",
            "hour_cap": 4,
            "day_cap": 5,
            "pacing": 6
        }
    ],
    "free_ad_source_list": [
        {
            "ad_source_id": 681851,
            "name": "Kuaishou Ads_int_2",
            "header_bidding_switch": 1,
            "ecpm": "50",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0"
        },
        {
            "ad_source_id": 681850,
            "name": "Mintegral_int_1",
            "header_bidding_switch": 1,
            "ecpm": "100",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0"
        },
        {
            "ad_source_id": 681854,
            "name": "Facebook_int_2",
            "header_bidding_switch": 1,
            "ecpm": "22",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0"
        }
    ]
}

 

Previous
Segment API
Next
Network API
Last modified: 2025-10-29Powered by