--- title: "Link Safety Check reference" url: "https://lookvalid.com/docs/api/link-safety.md" canonical_url: "https://lookvalid.com/docs/api/link-safety" last_updated: "2026-10-22" type: "reference" summary: "Request and response reference for Link Safety Check: parameters, response fields, credit cost and error codes." related: ["https://lookvalid.com/docs/errors.md"] --- # Link Safety Check reference Request and response reference for Link Safety Check: parameters, response fields, credit cost and error codes. Checks the domain of a URL against the CERT Polska Warning List of malicious domains, whose licence allows commercial use, and reports whether the domain or a parent domain is listed and the date of the list. A URL on no list is not proof it is safe: the list only holds domains that have already been reported, and it checks the domain, not the page. ```http POST https://YOUR_API_HOST/v1/link-safety ``` ## Credits and caching - Per-call billing. 1 credit per URL checked (a check that cannot run is free). Every completed lookup is charged, found or not. - Results are cached per account for 0 days. Repeating the same lookup in that window is free and returns `cache_hit: true`. - Invalid input, rate limits and errors are never charged. - Read the [billing rules](https://lookvalid.com/docs/credits-and-billing.md) for the full picture. ## Request Send a JSON body with `Authorization: Bearer `. The body can be up to 64 KB. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `url` | string | yes | Up to 2048 characters. | ### Example request **cURL** ```sh curl -X POST https://YOUR_API_HOST/v1/link-safety \ -H "Authorization: Bearer $LOOKVALID_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com"}' ``` **Node.js** ```js const response = await fetch("https://YOUR_API_HOST/v1/link-safety", { method: "POST", headers: { Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "url": "https://example.com" }), }); const result = await response.json(); if (!response.ok) throw new Error(`${result.error.code}: ${result.error.fix}`); console.log(result.found, result.data, result.credits_charged); ``` **Python** ```python import os import requests response = requests.post( "https://YOUR_API_HOST/v1/link-safety", headers={"Authorization": f"Bearer {os.environ['LOOKVALID_API_KEY']}"}, json={ "url": "https://example.com", }, timeout=30, ) result = response.json() if not response.ok: raise RuntimeError(f"{result['error']['code']}: {result['error']['fix']}") print(result["found"], result["data"], result["credits_charged"]) ``` ## Response The status is 200 whether or not anything was found. Check `found`. Every response also carries the `X-Request-Id`, `X-Credits-Charged`, `X-Credits-Remaining` and `X-RateLimit-*` headers. ### Envelope | Field | Type | Notes | | --- | --- | --- | | `request_id` | string | - | | `product` | "link-safety" | - | | `found` | boolean | False means the lookup ran and found nothing; it is free. | | `reason` | string or null | Why nothing was found; null when found. | | `sources` | array of string | Where the data came from, including any attribution the licence requires. | | `credits_charged` | integer | 0 for a cache hit, a not-found result or an error. | | `credits_remaining` | integer | - | | `cache_hit` | boolean | True when the account already paid for this lookup within the cache window. | | `cache` | object | - | ### The `data` object Present when `found` is true, otherwise `null`. | Field | Type | Notes | | --- | --- | --- | | `url` | string | - | | `host` | string | - | | `verdict` | string | One of `listed`, `not_listed`. | | `matches` | array of object | - | | `matches[].feed` | string | - | | `matches[].match_type` | string | One of `host`, `parent_domain`. | | `matches[].matched` | string | - | | `feeds_checked` | array of object | - | | `feeds_checked[].id` | string | - | | `feeds_checked[].name` | string | - | | `feeds_checked[].data_date` | string | When the feed data was published or last updated | | `feeds_checked[].matched` | boolean | - | | `feeds_checked[].licence` | string | - | | `feeds_unavailable` | array of object | - | | `feeds_unavailable[].id` | string | - | | `feeds_unavailable[].name` | string | - | | `feeds_unavailable[].reason` | string | - | | `disclaimer` | string | - | ### Captured example (2026-10-18) A real run of this lookup on 2026-10-18, using the request above, which is a public input. The envelope fields are left out. ```json { "product": "link-safety", "found": true, "data": { "url": "https://example.com/", "host": "example.com", "verdict": "not_listed", "matches": [], "feeds_checked": [ { "id": "cert-pl-warning-list", "name": "CERT Polska Warning List of malicious domains", "data_date": "2026-10-18T03:00:12.000Z", "matched": false, "licence": "Free for any purpose including commercial use (CERT Polska), no attribution required" } ], "feeds_unavailable": [], "disclaimer": "A URL on no list is not proof it is safe: the list only holds domains that have already been reported, and it checks the domain, not the page. A listed domain can be a compromised site that is now clean. Feeds that could not be checked are named under feeds_unavailable." }, "sources": [ "CERT Polska Warning List of malicious domains (Free for any purpose including commercial use (CERT Polska), no attribution required), data of 2026-10-18" ] } ``` ## Errors - `400` [`invalid_input`](https://lookvalid.com/docs/errors.md#invalid_input): The request input is invalid. - `401` [`unauthorized`](https://lookvalid.com/docs/errors.md#unauthorized): The API key is missing, malformed, revoked or unknown. - `402` [`insufficient_credits`](https://lookvalid.com/docs/errors.md#insufficient_credits): The account does not have enough credits for this lookup. Error code: insufficient_credits. During a trial whose allowance is used up the code is trial_allowance_exhausted: nothing is charged and the customer starts the plan from the billing page. - `405` [`method_not_allowed`](https://lookvalid.com/docs/errors.md#method_not_allowed): This endpoint does not accept that HTTP method. - `413` [`payload_too_large`](https://lookvalid.com/docs/errors.md#payload_too_large): The request body is too large. - `429` [`rate_limited`](https://lookvalid.com/docs/errors.md#rate_limited): Too many requests for this API key. - `500` [`internal_error`](https://lookvalid.com/docs/errors.md#internal_error): An unexpected error occurred. - `503` [`provider_unavailable`](https://lookvalid.com/docs/errors.md#provider_unavailable): The data source for this product is unavailable right now. ## Related - [Errors](https://lookvalid.com/docs/errors.md)