---
title: "Scan a domain for active phishing lookalikes"
method: POST
path: "/v1/metered/domain"
tags: ["Domain and infrastructure"]
---

# Scan a domain for active phishing lookalikes

`POST /v1/metered/domain`

## Request

- Base URL: `https://api.relayshield.net`
- URL: `https://api.relayshield.net/v1/metered/domain`
- Auth: one of:
  - API key in header `X-RS-API-KEY`
  - HTTP bearer

Generates typosquat, homoglyph and phishing-prefix permutations, keeps the ones that actually resolve, then enriches each with Safe Browsing status, registration age and Certificate Transparency activity. A lookalike registered in the last 30 days with a fresh certificate is being stood up right now.

**Billing.** $0.30 per successful call. Failed calls are never billed. Charged against prepaid credits when the balance covers it, otherwise metered to your card. Threat Intelligence subscribers and AWS Marketplace bundle customers call this at no extra charge.

**Note.** Enrichment is bounded to 15 seconds. A lookalike whose enrichment does not finish in time is still returned, with its enrichment fields set to null rather than omitted -- null means unknown here, never 'clean'.

## Request body

- object
  - `domain` string, required: Domain to protect. A scheme or leading `www.` is stripped for you.

## Response `200`

Success. `ok` is true and `data` holds the result.

- object
  - `ok` true, required
  - `data` object, required
    - `observed_at` string, date-time: When this verdict was observed. Cache keyed on this, not on receipt time.
    - `valid_for_seconds` integer: How long this verdict can be cached before it should be re-checked. Flagged results live 24 hours; clean results live 1 hour, because a hit stays a hit while a clean answer is the one that flips without telling whoever cached it. A degraded result lives 5 minutes. This is a caching hint and a policy default, not a measurement and not a safety guarantee: how fast a verdict really goes stale is bounded by upstream detection latency, which we do not control.
    - `expires_at` string, date-time: observed_at plus valid_for_seconds, precomputed.
    - `degraded` boolean: True when this answer was assembled from incomplete or failed upstream data. Treat it as NO VERDICT, never as clean. An outage that returns an empty finding list is otherwise indistinguishable from a real all-clear, and it fails in the permissive direction.
    - `domain` string: The normalised domain that was scanned.
    - `lookalikes_found` integer: Permutations that resolve.
    - `lookalikes` object[]: One entry per active lookalike.
      - `domain` string: The lookalike domain that resolves.
      - `gsb_flagged` boolean, nullable: True if Google Safe Browsing lists it. null when enrichment timed out.
      - `registration_age_days` integer, nullable: Days since registration via RDAP. Under 30 is a strong phishing signal. null when unavailable.
      - `cert_count` integer, nullable: Certificates seen in Certificate Transparency logs.
      - `cert_recent` boolean, nullable: True if a certificate was issued recently, indicating the lookalike is being stood up now.
      - `latest_cert_issued` string, nullable: Issue date of the most recent certificate.
    - `candidates_checked` integer: Permutations actually resolved within the scan window. Previously this reported the number generated, which overstated coverage whenever the sweep was truncated.
    - `candidates_total` integer: Permutations generated for this domain.
    - `candidates_unchecked` integer: Permutations whose DNS lookup did not finish in time. Non-zero means the sweep was truncated, `degraded` is true, and a low lookalikes_found is not evidence that the domain is clean.
    - `checked_at` string, date-time: ISO 8601 UTC timestamp of when this check ran.

## Other responses

- `400`: `domain` is missing or contains no '.'.
- `401`: Missing or invalid API key.
- `402`: No credits and no active subscription. The response carries `topup_url`.
- `405`: Wrong HTTP method. Every endpoint is POST.

---

[API](https://skmtc.dev/relayshield/apis/relayshield-api.md) · [All operations](https://skmtc.dev/relayshield/apis/relayshield-api/llms.txt) · [OpenAPI document](https://skmtc.dev/relayshield/apis/relayshield-api/revisions/4d4721b936dd?raw)