> ## Documentation Index
> Fetch the complete documentation index at: https://docs.greip.io/llms.txt
> Use this file to discover all available pages before exploring further.
# IP Scoring
> Access comprehensive threat intelligence data linked to a specific IP address. This endpoint provides insights into malicious activity, reputation scoring, and potential security risks associated with the IP address.
export const MCPCallout = () => {
return
;
};
## Authentication
Include your API key in the `Authorization` header:
```http theme={null}
Authorization: Bearer
```
API v2 accepts the key only in this header, not in query parameters or request bodies. See [Authentication](/authentication).
### Path parameters
The IP address you want to retrieve threat intelligence for.
Expected values: an IP address (IPv4 or IPv6)
Sample value: `1.1.1.1`
### Query parameters
The format command is used to get a response in a specific format.
Expected values: `JSON`, `XML`, `CSV`, or `Newline`
For more information please refer to [Response format](/options/response-format).
The mode command is used in the development stage to simulate the integration process before releasing it to the production environment.
Expected values: `live`, or `test`.
For more information please refer to [Development environment](/options/development-environment).
Optional label for your own analytics or support correlation (for example a product or channel name).
The user\_id command can be used to identify requests sent by specific users to monitor in the [Events page](/knowledge-base/events-and-alerts/overview).
Expected values: email address, phone number, user id, name, etc.
For more information please refer to [User identifier](/options/user-identifier).
```json Success theme={null}
{
"success": true,
"data": {
"ip": "12.12.12.12",
"score": 35,
"risk_level": "medium",
"recommendation": "review",
"rules": [
{
"id": "IP_VPN_OR_PROXY",
"description": "IP address is associated with VPN, proxy, or anonymization service."
},
{
"id": "IP_HOSTING",
"description": "IP address belongs to hosting or cloud provider ASN."
}
],
"security": {
"vpn_or_proxy": true,
"vpn_or_proxy_type": "Socks",
"tor": false,
"bot": false,
"relay": false,
"relay_country": null,
"relay_city": null,
"hosting": true,
"is_blacklisted": false
},
"custom_rules_applied": {
"total": 0,
"rules": []
}
},
"execution_ms": 90
}
```
```json Error theme={null}
{
"success": false,
"code": 101,
"type": "invalid_key",
"description": "The API Key is missing or invalid."
}
```
### Response properties
`true` when the request succeeded; `false` on error.
IP address you're looking up.
Composite threat score from 0 to 100 derived from the `security` module.
A higher score means higher risk.
Risk band (`low`, `medium`, or `high`) from the composite score.
Suggested action (`accept`, `review`, or `reject`).
Each object has `id` and `description`. The array lists only signals that fired for this request (empty when none apply).
| Id | Description |
| - | - |
| `IP_BLACKLISTED` | IP address is on a Greip threat list or your custom blocklist. |
| `IP_TOR` | IP address is a known Tor exit node. |
| `IP_VPN_OR_PROXY` | IP address is associated with VPN, proxy, or anonymization service. |
| `IP_RELAY` | IP address matches a private relay or similar anonymization pattern. |
| `IP_BOT` | Request user-agent matches automated bot patterns. |
| `IP_HOSTING` | IP address belongs to hosting or cloud provider ASN. |
Indicates if the IP address is a proxy service.
Type of proxy used.
Indicates if accessed through Tor network.
Indicates if the user is a bot.
Indicates if it's a Apple's Private Relay connection.
Country code for Apple Private Relay when detected; otherwise `null`.
City for Apple Private Relay when detected; otherwise `null`.
Indicates if the IP address belong to a hosting provider.
Indicates if the IP address is blacklisted due to applying [custom
rules](/knowledge-base/custom-rules/overview) or were found in one of
your blacklists.
The custom rules applied to this request, [learn
more](/knowledge-base/custom-rules/overview).
The total number of custom rules applied to this request.
Custom rules that matched this request.
The rule ID as shown in the dashboard (e.g: `CR104`).
The rule title you set when creating the rule.
Time taken to process the request (milliseconds).
## OpenAPI
````yaml openapi/v2.json GET /score/ip/{ip}
openapi: 3.0.3
info:
title: Greip API v2 (docs playground)
version: 2.0.0
servers:
- url: https://v2.greipapi.com
security: []
paths:
/score/ip/{ip}:
get:
summary: IP scoring
operationId: scoreIp
parameters:
- name: ip
in: path
required: true
schema:
type: string
- name: format
in: query
schema:
type: string
default: JSON
- name: mode
in: query
schema:
type: string
default: live
- name: source
in: query
schema:
type: string
- name: user_id
in: query
schema:
type: string
responses:
'200':
description: OK
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.