As of April 2022, you can have optional IP velocity fields returned as part of the Verify v4 API response. To have these fields included, contact your CSM (Customer Success Manager). They are available in both Arkose Detect and Arkose Protect.

When enabled, the IP velocity fields and their values appear in the Verify v4 API response as an "aggregations" field with subfields and their values as shown. The short_term fields are for detecting volumetric attacks, while the long_term fields are for detecting low & slow attacks.

"aggregations": {
        "ip": {
            "short_term": {
                "interval_minutes": 60,
                "count": 22,
                "threshold": 11
            },
            "long_term": {
                "interval_minutes": 720,
                "count": 22,
                "threshold": 50
            }
        },

The fields' meanings and allowed values are:

Field	Subfield	Subfield	Subfield	Description and Values
`"aggregations"`
	`"ip"`			Data consists of aggregated over time sightings of an IP address on a customer’s key.
		`"short_term"`		A shorter time bucket for detecting volumetric attacks.
			`"interval_minutes"`	The period of time over which the aggregation was done. For example, if this value is `10` and `short_term`'s `count` value is `6`, it means the IP address was seen 6 times on a customer's key within the last 10 minutes. A non-negative integer.
			`"count"`	Number of times an IP address was seen on a public key for the duration defined in `short_term`'s `interval_minutes` value. A non-negative integer.
			`"threshold"`	The threshold set on the public key. A threshold is determined based on historical data. As a rule of thumb, if the `short _term` `count` value exceeds the `short_term` `threshold` value, you should be suspicious of a volumetric attack. A non-negative integer.
		`"long_term"`		A longer time bucket for detecting low & slow attacks.
			`"interval_minutes"`	The period of time over which the aggregation was done. For example, if this value is `20` and `long_term`'s `count` value is `12`, it means the IP address was seen 12 times on a customer's key within the last 20 minutes. A non-negative integer.
			`"count"`	Number of times an IP address was seen on a public key for the duration defined in `long_term`'s `interval_minutes` value. A non-negative integer.
			`"threshold"`	The threshold set on the public key. A threshold is determined based on historical data. As a rule of thumb, if the `long_term` `count` value exceeds the `long_term` `threshold` value, you should be suspicious of a low & slow attack. A non-negative integer.

Error Handling

If the IP Velocity fields have been turned on and there was an error limited to them that does not apply to the other Verify API response fields, the following is returned in the Verify response. Note that you must include in any code you write to handle the IP Velocity fields a way of detecting and handling this error response.

"aggregations":
{
"error": "unable to contact service"
},

The overall Verify API response need not show an HTTP error code. If it does, it will be handled by the overall Verify error code logic. This error code block is orthogonal to any overall error that Verify may send as a response. In other words, even if "aggregations" shows the above error, the overall Verify API response can still show a 200 successful code.