Latency Testing API

Ddosify Latency Testing API

You can instantly start a geo-targeted latency test or you can create/delete/update a latency test plan to re-use it with Latency API.

Geo-Targeting

You will see the locations key in the request body of related API endpoints. The usage of this key let you able to perform latency test for desired locations.

Format of locations Object

You can target from continent to city by using the below format.

["<continent_code>.<country_code>.<state_code_if_exists>.<city_code>", ...]

Example Usages of locations Object

locationsTarget Locations

["NA.US.TX.DA"]

Dallas

["NA.US.TX.*"]

All supported cities in Texas

["NA.US.*"]

All supported cities in USA

["EU.FR.PR"]

Paris

["NA.US.*", "EU.FR.PR"]

All supported cities in USA and Paris

["*"]

All supported cities

Endpoints

All endpoints require the X-API-KEY header for authentication. Please check the Get Your API Key section to learn how you can get it.

You'll be charged for 5K Requests for every successful latency test.

API concurrency limit is 5 requests per second for GET endpoints and 2 requests per second for others. You will get HTTP 429 (Concurrency Limit Exceeded) when you reach the concurrency.

Get supported latency locations

GET https://api.ddosify.com/v1/latency/locations/

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

{
    "AF:Africa": {
        "ZA:South Africa": {
            "WC:Western Cape": [
                "CT:Cape Town"
            ],
            "GP:Gauteng": [
                "JO:Johannesburg"
            ]
        }
    },
    "AS:Asia": {
        "SG:Singapore": {
            "01:Central Singapore": [
                "SI:Singapore"
            ]
        },
        "CN:China": {
            "HCW:Central and Western": [
                "HK:Hong Kong"
            ]
        },
        "ID:Indonesia": [
            "JK:Jakarta"
        ],
        "JP:Japan": [
            "OS:Osaka",
            "TO:Tokyo"
        ],
        "KR:Korea": [
            "SE:Seoul"
        ],
        "BH:Bahrain": [
            "MA:Manama"
        ],
        "AE:United Arab Emirates": [
            "DU:Dubai"
        ],
        "IN:India": {
            "MH:Maharashtra": [
                "MU:Mumbai",
                "PU:Pune"
            ],
            "DL:Delhi": [
                "ND:New Delhi"
            ]
        },
        "QA:Qatar": {
            "DA:Baladiyat ad Dawhah": [
                "DO:Doha"
            ]
        },
        "TW:Taiwan": [
            "TP:Taipei"
        ],
        "IL:Israel": [
            "TA:Tel Aviv"
        ],
        "TR:Turkey": [
            "DE:Denizli",
            "IS:Istanbul",
            "AN:Ankara",
            "IZ:Izmir"
        ]
    },
    "EU:Europe": {
        "CH:Switzerland": [
            "ZH:Zurich"
        ],
        "IE:Ireland": {
            "L:Leinster": [
                "DU:Dublin"
            ]
        },
        "GB:United Kingdom": {
            "ENG:England": [
                "LO:London"
            ]
        },
        "IT:Italy": {
            "25:Lombardy": [
                "MI:Milan"
            ]
        },
        "FR:France": {
            "IDF:Ile-de-France": [
                "PA:Paris"
            ]
        },
        "SE:Sweden": [
            "ST:Stockholm"
        ],
        "DE:Germany": {
            "HE:Hesse": [
                "FR:Frankfurt"
            ]
        },
        "NL:Netherlands": {
            "NH:North Holland": [
                "AM:Amsterdam"
            ]
        },
        "NO:Norway": [
            "OS:Oslo"
        ],
        "PL:Poland": {
            "MZ:Masovian Voivodeship": [
                "WA:Warsaw"
            ]
        },
        "FI:Finland": {
            "SK:South Karelia": [
                "LA:Lappeenranta"
            ]
        },
        "ES:Spain": [
            "MA:Madrid"
        ]
    },
    "NA:North America": {
        "US:United States": {
            "TX:Texas": [
                "HO:Houston",
                "SA:San Antonio",
                "DA:Dallas"
            ],
            "IL:Illinois": [
                "CH:Chicago"
            ],
            "GA:Georgia": [
                "AT:Atlanta"
            ],
            "MO:Missouri": [
                "KC:Kansas City"
            ],
            "FL:Florida": [
                "MI:Miami"
            ],
            "MN:Minnesota": [
                "MI:Minneapolis"
            ],
            "PA:Pennsylvania": [
                "PH:Philadelphia"
            ],
            "CO:Colorado": [
                "DE:Denver"
            ],
            "CA:California": [
                "LA:Los Angeles",
                "SJ:San Jose"
            ],
            "VA:Virginia": [
                "AS:Ashburn"
            ],
            "OH:Ohio": [
                "DU:Dublin"
            ],
            "OR:Oregon": [
                "PO:Portland"
            ],
            "IA:Iowa": [
                "DM:Des Moines"
            ],
            "WA:Washington": [
                "QU:Quincy",
                "SE:Seattle"
            ],
            "SC:South Carolina": [
                "NC:North Charleston"
            ],
            "NV:Nevada": [
                "LV:Las Vegas"
            ],
            "UT:Utah": [
                "SLC:Salt Lake City"
            ],
            "AZ:Arizona": [
                "PH:Phoenix"
            ],
            "MA:Massachusetts": [
                "BO:Boston"
            ],
            "NJ:New Jersey": [
                "NY:New York"
            ]
        },
        "CA:Canada": {
            "QC:Quebec": [
                "MO:Montreal"
            ],
            "ON:Ontario": [
                "TO:Toronto"
            ]
        }
    },
    "SA:South America": {
        "BR:Brazil": [
            "SA:Sao Paulo"
        ],
        "CL:Chile": {
            "RM:Santiago Metropolitan": [
                "SA:Santiago"
            ]
        }
    },
    "OC:Oceania": {
        "AU:Australia": {
            "NSW:New South Wales": [
                "SY:Sydney"
            ],
            "VIC:Victoria": [
                "ME:Melbourne"
            ]
        }
    }
}

Start a latency test. You'll be charged for 5K Requests

POST https://api.ddosify.com/v1/latency/test/

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

Request Body

NameTypeDescription

target*

String

Target URL or IP address.

Example: https://example.com

locations*

Array

locations object.

Example: ["NA.US.*", "EU.FR.PR"]

{
    "AS.TR.AN": {
        "status_code": 200,
        "latency": 74
    },
    "NA.US.UT.SLC": {
        "status_code": 200,
        "latency": 148
    },
    "NA.US.NV.LV": {
        "status_code": 200,
        "latency": 200
    },
    "OC.AU.NSW.SY": {
        "status_code": 200,
        "latency": 294
    },
    "AS.IN.MH.PU": {
        "status_code": 200,
        "latency": 143
    },
    "AS.AE.DU": {
        "status_code": 200,
        "latency": 126
    },
    "AS.ID.JK": {
        "status_code": 200,
        "latency": 261
    },
    "AS.CN.HCW.HK": {
        "status_code": 200,
        "latency": 209
    },
    "NA.US.OR.PO": {
        "status_code": 200,
        "latency": 183
    },
    "NA.US.WA.QU": {
        "status_code": 200,
        "latency": 162
    },
    "AS.TR.IZ": {
        "status_code": 200,
        "latency": 61
    },
    "EU.ES.MA": {
        "status_code": 200,
        "latency": 46
    },
    "EU.PL.MZ.WA": {
        "status_code": 200,
        "latency": 32
    },
    "AS.TW.TP": {
        "status_code": 200,
        "latency": 259
    },
    "EU.DE.HE.FR": {
        "status_code": 200,
        "latency": 16
    },
    "AF.ZA.WC.CT": {
        "status_code": 200,
        "latency": 173
    },
    "EU.CH.ZH": {
        "status_code": 200,
        "latency": 22
    },
    "NA.US.CA.SJ": {
        "status_code": 200,
        "latency": 169
    },
    "SA.CL.RM.SA": {
        "status_code": 200,
        "latency": 221
    },
    "EU.FI.SK.LA": {
        "status_code": 200,
        "latency": 68
    },
    "AS.TR.IS": {
        "status_code": 200,
        "latency": 57
    },
    "NA.US.TX.DA": {
        "status_code": 200,
        "latency": 161
    },
    "NA.US.TX.HO": {
        "status_code": 200,
        "latency": 131
    },
    "AS.TR.DE": {
        "status_code": 200,
        "latency": 64
    },
    "AS.IL.TA": {
        "status_code": 200,
        "latency": 74
    },
    "OC.AU.VIC.ME": {
        "status_code": 200,
        "latency": 304
    },
    "EU.SE.ST": {
        "status_code": 200,
        "latency": 40
    },
    "NA.US.OH.DU": {
        "status_code": 200,
        "latency": 110
    },
    "NA.US.IL.CH": {
        "status_code": 200,
        "latency": 123
    },
    "AS.BH.MA": {
        "status_code": 200,
        "latency": 118
    },
    "EU.NO.OS": {
        "status_code": 200,
        "latency": 35
    },
    "NA.US.AZ.PH": {
        "status_code": 200,
        "latency": 147
    },
    "NA.US.IA.DM": {
        "status_code": 200,
        "latency": 129
    },
    "AS.IN.DL.ND": {
        "status_code": 200,
        "latency": 275
    },
    "EU.FR.IDF.PA": {
        "status_code": 200,
        "latency": 28
    },
    "AS.SG.01.SI": {
        "status_code": 200,
        "latency": 172
    },
    "AS.KR.SE": {
        "status_code": 200,
        "latency": 284
    },
    "EU.IE.L.DU": {
        "status_code": 200,
        "latency": 40
    },
    "NA.CA.QC.MO": {
        "status_code": 200,
        "latency": 110
    },
    "NA.US.SC.NC": {
        "status_code": 200,
        "latency": 113
    },
    "EU.IT.25.MI": {
        "status_code": 200,
        "latency": 22
    },
    "AF.ZA.GP.JO": {
        "status_code": 200,
        "latency": 192
    },
    "EU.NL.NH.AM": {
        "status_code": 200,
        "latency": 23
    },
    "AS.QA.DA.DO": {
        "status_code": 200,
        "latency": 137
    },
    "NA.US.VA.AS": {
        "status_code": 200,
        "latency": 106
    },
    "NA.CA.ON.TO": {
        "status_code": 200,
        "latency": 121
    },
    "AS.JP.TO": {
        "status_code": 200,
        "latency": 251
    },
    "AS.JP.OS": {
        "status_code": 200,
        "latency": 256
    },
    "AS.IN.MH.MU": {
        "status_code": 200,
        "latency": 138
    },
    "EU.GB.ENG.LO": {
        "status_code": 200,
        "latency": 28
    },
    "SA.BR.SA": {
        "status_code": 200,
        "latency": 218
    },
    "NA.US.TX.SA": {
        "status_code": 200,
        "latency": 151
    }
}

Create a new latency test plan

POST https://api.ddosify.com/v1/latency/plan/

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

Request Body

NameTypeDescription

name*

String

Test plan name

target*

String

Target URL or IP address. Example: https://example.com

locations*

Array

locations object.

Example: ["NA.US.*", "EU.FR.PR"]

{
    "plan_id": "476d4f04-402d-4bbd-8032-4f0309df5dd2"
}

Start a latency test with the plan id. You'll be charged for 5K Requests

POST https://api.ddosify.com/v1/latency/plan/<PLAN_ID>/test/

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

{
    "AS.CN.HCW.HK": {
        "status_code": 200,
        "latency": 210
    },
    "AS.TR.AN": {
        "status_code": 200,
        "latency": 72
    },
    "AS.AE.DU": {
        "status_code": 200,
        "latency": 129
    },
    "AS.ID.JK": {
        "status_code": 200,
        "latency": 264
    },
    "AS.IN.MH.PU": {
        "status_code": 200,
        "latency": 144
    },
    "AS.TR.IS": {
        "status_code": 200,
        "latency": 58
    },
    "AS.QA.DA.DO": {
        "status_code": 200,
        "latency": 143
    },
    "AS.SG.01.SI": {
        "status_code": 200,
        "latency": 193
    },
    "AS.IN.MH.MU": {
        "status_code": 200,
        "latency": 131
    },
    "AS.BH.MA": {
        "status_code": 200,
        "latency": 101
    },
    "AS.TW.TP": {
        "status_code": 200,
        "latency": 268
    },
    "AS.TR.IZ": {
        "status_code": 200,
        "latency": 60
    },
    "AS.IL.TA": {
        "status_code": 200,
        "latency": 75
    },
    "AS.TR.DE": {
        "status_code": 200,
        "latency": 61
    },
    "AS.JP.TO": {
        "status_code": 200,
        "latency": 249
    },
    "AS.KR.SE": {
        "status_code": 200,
        "latency": 277
    },
    "AS.IN.DL.ND": {
        "status_code": 200,
        "latency": 280
    },
    "AS.JP.OS": {
        "status_code": 200,
        "latency": 267
    }
}

Retrieve details of the latency test plan

GET https://api.ddosify.com/v1/latency/plan/<PLAN_ID>/

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

{
    "id": "25187168-bfc6-4134-a1ea-b8d6fe329f7f",
    "name": "test plan",
    "target": "https://servdown.com",
    "test_count": 2,
    "date_created": "2022-11-20T20:52:34.574396Z",
    "locations": [
        "AF.ZA.GP.JO",
        "AF.ZA.WC.CT"
    ]
}

Get latency test plans

GET https://api.ddosify.com/v1/latency/plan/

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

[
    {
        "id": "25187168-bfc6-4134-a1ea-b8d6fe329f7f",
        "name": "test plan",
        "target": "https://servdown.com",
        "test_count": 2,
        "date_created": "2022-11-20T20:52:34.574396Z",
        "locations": [
            "AF.ZA.GP.JO",
            "AF.ZA.WC.CT"
        ]
    },
    {
        "id": "1ef04daf-0787-4687-ba74-a89a291976ad",
        "name": "test plan 2",
        "target": "https://app.servdown.com",
        "test_count": 3,
        "date_created": "2022-10-20T20:52:34.574396Z",
        "locations": [
            "AS.AE.DU",
            "AS.BH.MA",
            "AS.ID.JK",
            "AS.IL.TA",
            "AS.JP.OS",
            "AS.JP.TO",
            "AS.KR.SE",
            "AS.TR.AN",
            "AS.TR.DE",
            "AS.TR.IS",
            "AS.TR.IZ",
            "AS.TW.TP",
            "AS.IN.DL.ND",
            "AS.IN.MH.MU",
            "AS.IN.MH.PU",
            "AS.QA.DA.DO",
            "AS.SG.01.SI",
            "AS.CN.HCW.HK"
        ]
    },
    {
        "id": "dc9d7d8e-ddff-4164-bf44-92d13bdc4036",
        "name": "test plan 1",
        "target": "https://app.servdown.com",
        "test_count": 0,
        "date_created": "2022-10-19T20:52:34.574396Z",
        "locations": [
            "AS.TR.AN",
            "AS.TR.IS"
        ]
    }
]

Update the latency test plan

PUT https://api.ddosify.com/v1/latency/plan/<PLAN_ID>/

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

Request Body

NameTypeDescription

name

String

Test plan name

target

String

Target URL or IP address. Example: https://example.com

locations

Array

locations object.

Example: ["NA.US.*", "EU.FR.PR"]

Delete the latency test plan

DELETE https://api.ddosify.com/v1/latency/plan/<PLAN_ID>/

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

Get available credit

GET https://api.ddosify.com/v1/balance/

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

{
    "request_count": 295010,
    "duration": 20
}

Scheduling

You can create periodic latency tests with the scheduling mechanism. The scheduler is basically a wrapper over Latency Test Plan to make it periodically runnable with the given configurations.

Scheduler Object

KeyValueDescription

name

String

Scheduler name

interval

String

Interval time between each run. Format: "(digit)(s|m|h)" Examples: "30s" : Runs every 30 seconds "4m" : Runs every 4 minutes "1h" : Runs every 1 hour

is_active

Bool

Enable/disable logic for the scheduler

total_run_count

Integer

The maximum number of run counts for the scheduler. If it is null then the scheduler runs forever.

test_plan_id

UUID

Latency Test Plan to be used by scheduler

run_count

Integer

This is a read-only field and is updated by the scheduler every time a test is finished.

The minimum interval value is "30s".

Lifecycle of a Scheduler

At the beginning of each interval, the Scheduler first checks is_active to be sure that the scheduler is active. Then it controls if the number of test runs reached its maximum value by comparing total_run_count with run_count. If these two checks passed, the scheduler starts a new Latency Test by using the Latency Test Plan.

Be careful about the infinite Schedulers (whentotal_run_count is null). They run forever until you stop them.

Create a scheduler

POST https://api.ddosify.com/v1/latency/scheduler

You will be charged for every latency test started by the Scheduler. The charging cost is the same as the normal Latency Test cost.

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

Request Body

NameTypeDescription

name*

String

Scheduler name

interval*

String

Interval time between each run. Minimum value is "30s"

is_active*

Bool

Enable/disable logic for the scheduler

total_run_count

Integer

The maximum number of run counts. No need to add this for infinite schedulers.

test_plan_id*

UUID

Latency Test Plan id

{
    "msg": "detail..."
}

Retrieve details of the scheduler

GET https://api.ddosify.com/v1/latency/scheduler/<SCHEDULER_ID>/

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

{
    "id": "efe7595a-e29a-4be8-bf5c-d38a07585b20",
    "name": "Latency Scheduler 1",
    "interval": "30s",
    "is_active": false,
    "total_run_count": null,
    "run_count": 5,
    "test_plan_id": "3eedf757-3259-4232-9509-e46c80856831"
}

List all the schedulers

GET https://api.ddosify.com/v1/latency/scheduler/

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

[
    {
        "id": "b90b2d7b-9704-46c4-b05b-cbda624ebd04",
        "name": "Latency Scheduler 1",
        "interval": "30s",
        "is_active": true,
        "total_run_count": null,
        "run_count": 11,
        "test_plan_id": "3eedf757-3259-4232-9509-e46c80856831",
        "test_plan_name": "Test plan example 1"
    },
    {
        "id": "37638916-7dcd-4f2b-bea0-6a5c99d4a04d",
        "name": "Latency Scheduler 2",
        "interval": "1m",
        "is_active": true,
        "total_run_count": 3,
        "run_count": 3,
        "test_plan_id": "901b825c-402e-4ca7-903a-2527a60c32ee",
        "test_plan_name": "Test plan example 2"
    }
]

List all the schedulers with Latency Test Plan ID

GET https://api.ddosify.com/v1/latency/scheduler?test_plan=<PLAN_ID>

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

[
    {
        "id": "b90b2d7b-9704-46c4-b05b-cbda624ebd04",
        "name": "Latency Scheduler 1",
        "interval": "30s",
        "is_active": true,
        "total_run_count": null,
        "run_count": 11,
        "test_plan_id": "3eedf757-3259-4232-9509-e46c80856831"
    },
    {
        "id": "37638916-7dcd-4f2b-bea0-6a5c99d4a04d",
        "name": "Latency Scheduler 2",
        "interval": "1m",
        "is_active": true,
        "total_run_count": 3,
        "run_count": 3,
        "test_plan_id": "3eedf757-3259-4232-9509-e46c80856831"
    }
]

Get the result of executed latency tests in descending order by date

GET https://api.ddosify.com/v1/latency/scheduler/<SCHEDULER_ID>/result/

You can filter the result by providing start and end timestamps as query parameters. This endpoint is paginated and the page size is 25. The count represents the total number of results.

Query Parameters

NameTypeDescription

start

Timestamp

end

Timestamp

page

Integer

Pagination

Headers

NameTypeDescription

X-API-KEY*

UUID

Your API KEY

{
    "next": "https://api.ddosify.com/v1/latency/scheduler/fd6c7383-b01a-4bea-b2f4-a5a3fc967d60/result?page=2",
    "previous": null,
    "count": 23,
    "results": [
        {
            "time": 1669119230721,
            "result": {
                "NA.CA.ON.TO": {
                    "status_code": 200,
                    "latency": 111
                },
                "NA.CA.QC.MO": {
                    "status_code": 200,
                    "latency": 97
                },
                "NA.US.AZ.PH": {
                    "status_code": 200,
                    "latency": 176
                },
                "NA.US.CA.LA": {
                    "status_code": 200,
                    "latency": 178
                },
                "NA.US.CA.SJ": {
                    "status_code": 200,
                    "latency": 181
                },
                "NA.US.CO.DE": {
                    "status_code": 200,
                    "latency": 167
                },
                "NA.US.FL.MI": {
                    "status_code": 200,
                    "latency": 126
                },
                "NA.US.GA.AT": {
                    "status_code": 200,
                    "latency": 123
                }
            }
        },
        {
            "time": 1669119200712,
            "result": {
                "NA.CA.ON.TO": {
                    "status_code": 200,
                    "latency": 125
                },
                "NA.CA.QC.MO": {
                    "status_code": 200,
                    "latency": 97
                },
                "NA.US.AZ.PH": {
                    "status_code": 200,
                    "latency": 178
                },
                "NA.US.CA.LA": {
                    "status_code": 200,
                    "latency": 174
                },
                "NA.US.CA.SJ": {
                    "status_code": 200,
                    "latency": 173
                },
                "NA.US.CO.DE": {
                    "status_code": 200,
                    "latency": 170
                },
                "NA.US.FL.MI": {
                    "status_code": 200,
                    "latency": 122
                },
                "NA.US.GA.AT": {
                    "status_code": 200,
                    "latency": 113
                }
            }
        },
        ...
    ]
}