Edge API Response Parameters
Overview
This section outlines how to make POST requests to the Arkose Labs Edge API, including endpoint structure, required headers, and request body format.
Response Body Parameters
Fields | Sub-Fields | Type | Description |
|---|---|---|---|
| string | Recommended action values: Note: | |
| string | Error message, if any | |
| object | Metadata about the evaluated session | |
| string | Unique session identifier | |
| string | Timestamp indicating when session was created | |
| string | Primary telltale reason or label | |
| array | List of all telltales associated with the session | |
| object | Information about the IP address and its attributes | |
| string | IP address of the user | |
| boolean | True if user is behind a known proxy | |
| boolean | True if user is using a VPN | |
| boolean | True if user is using Tor | |
| string | Country where the IP is located | |
| string | Region/state of the IP | |
| string | City of the IP | |
| string | Internet Service Provider | |
| boolean | True if connection is from a public access point | |
| string | Type of network | |
| string | Latitude of IP geolocation | |
| string | Longitude of IP geolocation | |
| string | Timezone | |
| number | Autonomous System Number associated with the IP | |
| object | Risk assessment results | |
| string | Risk classification | |
| string | Risk severity level: | |
| object | Covers the information related to Global Telltales | |
| number | Global risk score (0–100) | |
| array | Provides the breakdown of the telltales and the weight of each | |
| string | Provides the global telltale name | |
| number | Provides the score associated with the global telltale | |
| object | Covers the information related to Custom Telltales | |
| number | Custom risk score (0–100) | |
| array | Provides the breakdown of the telltales and the weight of each | |
| string | Provides the custom telltale name | |
| number | Provides the score associated with the custom telltale | |
email_intelligence | object | Assessment and metadata for the email address. | |
| string | The IP address of the user. | |
| boolean | Whether the IP is identified as a proxy. | |
| boolean | Whether the IP is associated with a VPN. | |
| boolean | Whether the IP belongs to a Tor exit node. | |
| string | Country of the IP. | |
| string | Region or state. | |
| string | City of origin. | |
| string | Internet Service Provider name. | |
| boolean | Indicates if IP is from a public hotspot or similar. | |
| string | Connection type (e.g., “Residential”, “Data Center”). | |
| string | Latitude of IP. | |
| string | Longitude of IP. | |
| string | Time zone of IP. | |
| integer | Autonomous System Number associated with IP. | |
| object | Aggregated request statistics for the IP | |
| string | Error String in case of errors during Aggregations | |
| object | IP-level aggregation | |
| object | Recent IP activity | |
| int | Time window in minutes | |
| int | Number of events seen | |
| int | Threshold for flagging | |
| object | Longer IP activity window (e.g., past 24 hours) | |
| int | Time window in minutes | |
| int | Number of events seen | |
| int | Threshold for flagging | |
| string | Error message if any occurred |
Response Schema
The POST request should include a JSON body structure as show in the example below.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "The edge-api response body schema",
"type": "object",
"properties": {
"recommended_action": {
"type": "string",
"enum": [
"",
"allow",
"block",
"challenge"
]
},
"session_details": {
"type": "object",
"properties": {
"session": {
"type": "string",
"default": ""
},
"session_created": {
"type": [
"string",
"null"
],
"format": "date-time",
"default": null
},
"telltale_user": {
"type": "string",
"minLength": 0,
"maxLength": 128
},
"telltale_list": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"minLength": 0,
"maxLength": 128
}
}
},
"required": [
"session",
"session_created",
"telltale_user",
"telltale_list"
]
},
"ip_intelligence": {
"type": "object",
"properties": {
"user_ip": {
"anyOf": [
{
"type": "string",
"format": "ipv4"
},
{
"type": "string",
"format": "ipv6"
},
{
"type": "null"
}
],
"default": null
},
"is_tor": {
"type": "boolean",
"default": false
},
"is_vpn": {
"type": "boolean",
"default": false
},
"is_proxy": {
"type": "boolean",
"default": false
},
"country": {
"type": [
"string",
"null"
],
"default": null
},
"region": {
"type": [
"string",
"null"
],
"default": null
},
"city": {
"type": [
"string",
"null"
],
"default": null
},
"isp": {
"type": [
"string",
"null"
],
"default": null
},
"public_access_point": {
"type": "boolean",
"default": false
},
"connection_type": {
"type": [
"string",
"null"
],
"default": null
},
"latitude": {
"type": [
"string",
"null"
],
"default": null
},
"longitude": {
"type": [
"string",
"null"
],
"default": null
},
"timezone": {
"type": [
"string",
"null"
],
"default": null
}
},
"required": [
"user_ip",
"is_tor",
"is_vpn",
"is_proxy",
"country",
"region",
"city",
"isp",
"public_access_point",
"connection_type",
"latitude",
"longitude",
"timezone"
]
},
"session_risk": {
"type": "object",
"properties": {
"risk_category": {
"type": [
"string",
"null"
],
"default": null
},
"risk_band": {
"type": [
"string",
"null"
],
"default": null
},
"global": {
"type": "object",
"properties": {
"score": {
"type": "number"
},
"telltales": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"weight": {
"type": "number"
}
}
}
}
}
},
"custom": {
"type": "object",
"properties": {
"score": {
"type": "number"
},
"telltales": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"weight": {
"type": "number"
}
}
}
}
}
}
},
"required": [
"risk_category",
"risk_band",
"global",
"custom"
]
},
"aggregations": {
"type": "object",
"properties": {
"error": {
"type": [
"string",
"null"
]
},
"ip": {
"type": "object",
"properties": {
"short_term": {
"type": "object",
"properties": {
"interval_minutes": {
"type": [
"integer",
"null"
]
},
"count": {
"type": [
"integer",
"null"
]
},
"threshold": {
"type": [
"integer",
"null"
]
}
}
},
"long_term": {
"type": "object",
"properties": {
"interval_minutes": {
"type": [
"integer",
"null"
]
},
"count": {
"type": [
"integer",
"null"
]
},
"threshold": {
"type": [
"integer",
"null"
]
}
}
}
}
}
}
},
"stateful_device_id": {
"type": "object",
"properties": {
"cookie_value": {
"type": "string",
"default": ""
}
},
"required": [
"cookie_value"
]
},
"email_intelligence": {
"type": "object",
"properties": {
"email_assessment": {
"type": "object",
"properties": {
"anomalous_handle_composition": {
"default": false,
"type": "boolean"
},
"deenumerated_domain_length": {
"type": "integer"
},
"deenumerated_email_address": {
"default": "",
"type": "string"
},
"deenumerated_email_handle_length": {
"default": 0,
"type": "integer"
},
"detumbled_email_address": {
"default": "",
"type": "string"
},
"detumbled_email_first_seen": {
"default": "",
"type": "string"
},
"detumbled_email_first_seen_in_days": {
"default": 0,
"type": "integer"
},
"domain_enrichment": {
"properties": {
"domain_age": {
"default": 0,
"type": "integer"
},
"domain_creation_date": {
"default": "",
"type": "string"
},
"domain_name_servers": {
"oneOf": [
{
"default": null,
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
]
},
"domain_org": {
"default": "",
"type": "string"
},
"domain_registration_country": {
"default": "",
"type": "string"
},
"error": {
"type": "string"
},
"is_disposable": {
"default": false,
"type": "boolean"
},
"is_domain_missing": {
"default": false,
"type": "boolean"
}
},
"type": "object"
},
"domain_metric_entropy": {
"type": "number"
},
"domain_relative_usage_factor": {
"default": 0,
"type": "number"
},
"domain_shannon_entropy": {
"type": "number"
},
"email_address": {
"default": "",
"type": "string"
},
"email_domain": {
"default": "",
"type": "string"
},
"email_handle_length": {
"default": 0,
"type": "integer"
},
"email_risk_score": {
"default": 0,
"type": "number"
},
"is_enumerated_email": {
"default": false,
"type": "boolean"
},
"is_invalid_email": {
"default": false,
"type": "boolean"
},
"is_mx_record_present": {
"default": false,
"type": "boolean"
},
"is_mx_valid": {
"default": false,
"type": "boolean"
},
"is_private_relay": {
"default": false,
"type": "boolean"
},
"is_role_email": {
"default": false,
"type": "boolean"
},
"is_suspicious_email_handle": {
"default": false,
"type": "boolean"
},
"is_tumbled_email": {
"default": false,
"type": "boolean"
},
"suggested_action": {
"default": "",
"type": "string"
}
}
},
"detumbled_email_stats": {
"type": "object",
"properties": {
"handle_dvorak_typing_distance": {
"default": 0,
"type": "number"
},
"handle_length": {
"default": 0,
"type": "integer"
},
"handle_num_alpha_chars": {
"default": 0,
"type": "integer"
},
"handle_num_consonants": {
"default": 0,
"type": "integer"
},
"handle_num_numeric_chars": {
"default": 0,
"type": "integer"
},
"handle_num_special_chars": {
"default": 0,
"type": "integer"
},
"handle_num_vowels": {
"default": 0,
"type": "integer"
},
"handle_qwerty_typing_distance": {
"default": 0,
"type": "number"
}
}
},
"total_email_counts": {
"type": "object",
"properties": {
"error": {
"description": "Error message if counts could not be retrieved for the aggregation",
"type": "string"
},
"long_term_count": {
"description": "Numeric count of the aggregation metric in long term",
"type": "integer"
},
"long_term_period_minutes": {
"description": "The time period over which the long term count was aggregated in minutes",
"type": "integer"
},
"short_term_count": {
"default": 0,
"description": "Numeric count of the aggregation metric in short term",
"type": "integer"
},
"short_term_period_minutes": {
"default": 0,
"description": "The time period over which the short term count was aggregated in minutes",
"type": "integer"
}
},
"required": [
"short_term_count",
"short_term_period_minutes"
]
},
"detumbled_email_unique_counts": {
"type": "object",
"properties": {
"error": {
"description": "Error message if counts could not be retrieved for the aggregation",
"type": "string"
},
"long_term_count": {
"description": "Numeric count of the aggregation metric in long term",
"type": "integer"
},
"long_term_period_minutes": {
"description": "The time period over which the long term count was aggregated in minutes",
"type": "integer"
},
"short_term_count": {
"default": 0,
"description": "Numeric count of the aggregation metric in short term",
"type": "integer"
},
"short_term_period_minutes": {
"default": 0,
"description": "The time period over which the short term count was aggregated in minutes",
"type": "integer"
}
},
"required": [
"short_term_count",
"short_term_period_minutes"
]
},
"deenumerated_email_unique_counts": {
"type": "object",
"properties": {
"error": {
"description": "Error message if counts could not be retrieved for the aggregation",
"type": "string"
},
"long_term_count": {
"description": "Numeric count of the aggregation metric in long term",
"type": "integer"
},
"long_term_period_minutes": {
"description": "The time period over which the long term count was aggregated in minutes",
"type": "integer"
},
"short_term_count": {
"default": 0,
"description": "Numeric count of the aggregation metric in short term",
"type": "integer"
},
"short_term_period_minutes": {
"default": 0,
"description": "The time period over which the short term count was aggregated in minutes",
"type": "integer"
}
},
"required": [
"short_term_count",
"short_term_period_minutes"
]
},
"domain_instance_counts": {
"type": "object",
"properties": {
"error": {
"description": "Error message if counts could not be retrieved for the aggregation",
"type": "string"
},
"long_term_count": {
"description": "Numeric count of the aggregation metric in long term",
"type": "integer"
},
"long_term_period_minutes": {
"description": "The time period over which the long term count was aggregated in minutes",
"type": "integer"
},
"short_term_count": {
"default": 0,
"description": "Numeric count of the aggregation metric in short term",
"type": "integer"
},
"short_term_period_minutes": {
"default": 0,
"description": "The time period over which the short term count was aggregated in minutes",
"type": "integer"
}
},
"required": [
"short_term_count",
"short_term_period_minutes"
]
},
"detumbled_email_instance_counts": {
"type": "object",
"properties": {
"error": {
"description": "Error message if counts could not be retrieved for the aggregation",
"type": "string"
},
"long_term_count": {
"description": "Numeric count of the aggregation metric in long term",
"type": "integer"
},
"long_term_period_minutes": {
"description": "The time period over which the long term count was aggregated in minutes",
"type": "integer"
},
"short_term_count": {
"default": 0,
"description": "Numeric count of the aggregation metric in short term",
"type": "integer"
},
"short_term_period_minutes": {
"default": 0,
"description": "The time period over which the short term count was aggregated in minutes",
"type": "integer"
}
},
"required": [
"short_term_count",
"short_term_period_minutes"
]
},
"domain_stats": {
"type": "object",
"properties": {
"domain_dvorak_typing_distance": {
"type": "number"
},
"domain_length": {
"type": "integer"
},
"domain_max_consec_consonants": {
"type": "integer"
},
"domain_max_consec_vowels": {
"type": "integer"
},
"domain_num_alpha_chars": {
"type": "integer"
},
"domain_num_consonants": {
"type": "integer"
},
"domain_num_numeric_chars": {
"type": "integer"
},
"domain_num_special_chars": {
"type": "integer"
},
"domain_num_vowels": {
"type": "integer"
},
"domain_qwerty_typing_distance": {
"type": "number"
}
}
},
"error": {
"type": "string"
}
},
"required": [
"total_email_counts"
]
},
"error": {
"description": "An description of the error that caused the request to fail (if any)",
"type": "string"
}
},
"required": [
"recommended_action",
"session_details",
"error"
]
}{
"recommended_action": "challenge",
"session_details": {
"session": "89818455d4249a528.5425182503",
"session_created": "2025-06-02T23:22:50Z",
"telltale_user": "g-rta-isp-velocity-short-term-abuse",
"telltale_list": [
"g-rta-isp-velocity-short-term-abuse"
]
},
"ip_intelligence": {
"user_ip": "18.224.115.223",
"is_proxy": true,
"is_vpn": true,
"is_tor": false,
"country": "US",
"region": "Ohio",
"city": "Columbus",
"isp": "Amazon.com",
"public_access_point": false,
"connection_type": "Data Center",
"latitude": "39.89",
"longitude": "-82.96",
"timezone": "America/New_York",
"asn": 16509
},
"session_risk": {
"risk_category": "BOT-STD",
"risk_band": "Low",
"global": {
"score": 20,
"telltales": [
{
"name": "g-rta-isp-velocity-short-term-abuse",
"weight": 20
}
]
},
"custom": {
"score": 0,
"telltales": []
}
},
"aggregations": {
"ip": {
"short_term": {
"interval_minutes": 60,
"count": 2,
"threshold": 11
},
"long_term": {
"interval_minutes": 1440,
"count": 3,
"threshold": 50
}
}
},
"email_intelligence": {
"email_assessment": {
"email_address": "[email protected]",
"detumbled_email_address": "[email protected]",
"deenumerated_email_address": "[email protected]",
"suggested_action": "email_no_risk",
"email_risk_score": 0,
"email_domain": "emaildomain.com",
"email_handle_length": 9,
"is_tumbled_email": false,
"is_enumerated_email": false,
"deenumerated_email_handle_length": 9,
"is_invalid_email": false,
"is_role_email": false,
"is_private_relay": false,
"detumbled_email_first_seen": "2025-09-25T23:33:23Z",
"detumbled_email_first_seen_in_days": 5,
"domain_relative_usage_factor": 1.3333333333333333,
"is_suspicious_email_handle": false,
"domain_shannon_entropy": 2.95,
"domain_metric_entropy": 0.3277777777777778,
"deenumerated_domain_length": 9,
"anomalous_handle_composition": false,
"is_mx_record_present": true,
"is_mx_valid": true,
"domain_enrichment": {
"is_domain_missing": false,
"domain_age": 11007,
"domain_creation_date": "2000-01-01",
"domain_org": "Email Domain LLC",
"domain_name_servers": [
"ns1.emaildomain.com",
"ns2.emaildomain.com"
],
"is_disposable": false,
"domain_registration_country": "US"
}
},
"detumbled_email_stats": {
"handle_length": 9,
"handle_num_alpha_chars": 9,
"handle_num_vowels": 3,
"handle_num_consonants": 6,
"handle_num_numeric_chars": 0,
"handle_num_special_chars": 0,
"handle_qwerty_typing_distance": 24.26455311860342,
"handle_dvorak_typing_distance": 31.458193116710234
},
"total_email_counts": {
"short_term_count": 1,
"short_term_period_minutes": 360,
"long_term_count": 5,
"long_term_period_minutes": 10080
},
"detumbled_email_unique_counts": {
"short_term_count": 1,
"short_term_period_minutes": 1440,
"long_term_count": 1,
"long_term_period_minutes": 21600
},
"deenumerated_email_unique_counts": {
"short_term_count": 1,
"short_term_period_minutes": 360
},
"domain_instance_counts": {
"short_term_count": 1,
"short_term_period_minutes": 360,
"long_term_count": 4,
"long_term_period_minutes": 10080
},
"domain_stats": {
"domain_length": 9,
"domain_num_alpha_chars": 8,
"domain_num_vowels": 3,
"domain_num_consonants": 0,
"domain_num_numeric_chars": 0,
"domain_num_special_chars": 1,
"domain_qwerty_typing_distance": 32.95709432711953,
"domain_dvorak_typing_distance": 40.36356408778201,
"domain_max_consec_consonants": 2,
"domain_max_consec_vowels": 2
}
},
"error": ""
}Updated 18 days ago