How do I start a network scan?

Requires Pro

Quick answer

Open the Discovery module, enter a target under New scan — a CIDR (10.0.0.0/24), a range (10.0.0.1-10.0.0.50), or a single IP — and click “Start scan”. The scan runs in the background; reachable devices then appear as discovered devices.

Prerequisites

The Discovery module is available from the Pro plan onward (feature Discovery). On lower plans, the section is locked and the API responds with 403.

Open the “Discovery” module. Choose Discovery in the left-hand navigation. At the top, you’ll find the New scan card.

Screenshot pending discovery-scan-01 The 'New scan' card in the Discovery module with the fields Target, Ports, and SNMP Community

The 'New scan' card — enter a target and start the scan.
Specify the target and options.
- Target — CIDR, range, or single IP (required).
- Ports (optional) — if left blank, Notory checks a sensible default selection (22, 80, 135, 139, 443, 445, 3389, 8080).
- SNMP community (optional) — if set, reachable hosts are additionally enriched via SNMP v2c (system name/description).
Click “Start scan”. The scan appears in the Scans list with the status Pending, changes to Running, and finally to Completed. After that, you can import the devices.

Screenshot pending discovery-scan-02 The 'Scans' list with status, host count, and discovered devices

The scans list with status, hosts checked, and number of finds.

Via the REST API: a POST to /api/v1/discovery/scans. Only target is required.

curl -X POST https://demo.notory.io/api/v1/discovery/scans \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "10.0.0.0/24",
    "ports": [22, 80, 443, 3389],
    "snmp_community": "public"
  }'

The API responds immediately with HTTP 201 Created; the scan runs asynchronously in the background (status initially pending):

{
  "id": "0190f3c0-1d10-7a20-9b30-2c40d50e6f70",
  "target": "10.0.0.0/24",
  "ports": [22, 80, 443, 3389],
  "status": "pending",
  "total_hosts": 0,
  "alive_hosts": 0,
  "discovered": 0,
  "error": null,
  "started_at": null,
  "finished_at": null,
  "created_at": "2026-07-08T10:30:00Z"
}

You poll progress via GET /api/v1/discovery/scans/{id} (status changes to running, then completed; discovered shows the number of finds).

Possible errors: 400 (invalid target or target too large — max 4096 hosts), 401, 403 (no write access or module not included in the plan).

What happens behind the scenes?

Asynchronous in the background: The call creates a scan job and queues it for processing (queue, otherwise in-process). The status progresses through Pending → Running → Completed (or Failed).
How the check works: Notory expands the target into individual hosts, tests the specified ports per host via TCP, and determines the hostname via reverse DNS. If no port responds, the host is considered unreachable.
Safety cap: A target may cover at most 4096 hosts; larger ranges are rejected with 400 so that no scan floods the network.
OS guess: From the open ports, Notory derives a rough estimate — open 3389/445/135 suggests Windows, an open port 22 suggests Linux/Unix.
SNMP enrichment (optional): With a community set, system name and description are added; if SNMP fails, the scan does not abort.
Result: Every reachable host is stored as a discovered device with the status New — still without an asset. Importing it is a separate step.