Skip to content
Loading...
API docs by Redocly

Netlas API (v1)

Download OpenAPI specification:

URL: https://netlas.io/ License: Netlas API & Data License Agreement Terms of Service
If you're new to the Netlas web app, we recommend starting here.

Environment

To interact with the Netlas API, you will need an API client or at least the curl command-line utility. Alternatively, you can use the Netlas CLI tool or the Netlas Python SDK.

This specification includes code samples for all of these options.

Setting Up an API Client

Most modern API clients support OpenAPI v3 imports. Click Download at the top of this page, then import the file into your preferred API client.

✅ We've confirmed that imports work smoothly in the following clients:

API Client Steps to Import
Postman In Import Settings, set Folder Organization to Tags for better structure.
Insomnia Collections → Create, then click the collection name in the top-left corner and choose Import From File.
Bruno Click Import Collection → OpenAPI V3 File, then choose a local folder to store the workspace.
Scalar Don’t forget to configure the API key in the collection's authentication settings.

Netlas CLI Tool

The Netlas CLI tool is ideal for users who prefer the command line or Bash scripting. It allows you to interact with Netlas just like any other terminal application.

To install the CLI via Homebrew:

brew tap netlas-io/netlas 
brew install netlas

Or install it using pipx:

pipx install netlas

Netlas Python SDK

The Netlas Python SDK is designed for Python developers. It provides a convenient way to work with the API, with built-in handling for common errors.

Install the SDK using pip:

pip install netlas

The Netlas CLI tool is included with the SDK, so it becomes available automatically after SDK installation. Both the Netlas Python SDK and CLI tool are open-source and available under the MIT license in the Github Netlas repository.

Netlas GitHub

Authentication

Each registered Netlas user receives a unique API key. You can find your API key on the profile page, accessible from the top-right menu in the web application.

API-key access

Include your API key as a Bearer token in the Authorization header to authorize your requests. The curl examples in this manual will work as-is if you export the API key as the NETLAS_API_KEY environment variable:

export NETLAS_API_KEY=put_your_key_here
curl -X 'GET' "https://app.netlas.io/api/host/" \
  -H "Authorization: Bearer $NETLAS_API_KEY"

Netlas API authorization follows RFC 6750, The OAuth 2.0 Authorization Framework: Bearer Token Usage.

The X-API-Key header was previously used for authentication and is still supported, but considered deprecated and may be removed in future versions.

If you are using the Netlas CLI or SDK, securely save your API key locally:

netlas savekey "YOUR_API_KEY"

The Netlas CLI tool automatically uses the saved key.

To fetch saved key in Python:

import netlas
api_key = netlas.helpers.get_api_key()

⚠️ FYI: You may be eligible for a special subscription if you're using Netlas for educational purposes, building an integration, or writing for a blog or journal.
Read more →

Rate Limits

To ensure fair usage and optimal performance, the Netlas API enforces the following rate limits:

  • 60 requests per minute for search and count operations, excluding certificate searches.
  • 3 requests per minute for search and count operations involving certificate data collections.

If these limits are exceeded, the API responds with Error 429 (Too Many Requests) and includes a Retry-After header indicating the number of seconds to wait before retrying.

The Netlas CLI and SDK are configured by default to automatically handle rate limit errors. When using the SDK, you can customize this behavior by setting the throttling and retry parameters in the search methods. This allows you to either disable automatic handling or specify the number of retry attempts.

To manage rate limiting manually you you can catch and handle the ThrottlingError exception in your code:

import netlas
import time

nc = netlas.Netlas()

for i in range(65):
    try:
        nc.host(host=None, fields=["*"], exclude_fields=True, throttling=False)
    except netlas.ThrottlingError as e:
        time.sleep(e.retry_after) # Wait for the specified time before retrying

⚠️ Important: Always handle Netlas API errors correctly. Ignoring rate limits or other errors may result in temporary access restrictions. Read more about blocking policy in the FAQ section.

Host Info

Retrieves a summary of Netlas data for a specific IP address or domain name.

The Host Info endpoint supports queries by IP or domain only, but returns aggregated data from all Netlas data collections in a single response.

The same data available in the Netlas web interface via the IP/Domain Info tool.

Host Summary

Retrieve the latest available data for {host}.

path Parameters
required
IPv4 (string) or Domain (string)

The IP address or domain name for which data should be retrieved.

query Parameters
fields
Array of strings (fields)
Default: "*"
Examples: fields=* fields=ip fields=ptr[0],whois.abuse

You can control the amount of output data by specifying which fields to include or exclude in the response. Use the source_type parameter to select between include and exclude options.

source_type
string (source_type)
Default: "include"
Enum: "include" "exclude"

Specify fields and use source_type to choose between:

  • include to return only the specified fields
  • exclude to return all fields except the specified ones
public_indices_only
boolean (public_indices_only)
Default: false
Example: public_indices_only=true

By default, data is requested from both private and public indices, returning the most recent results. Use this query parameter to restrict the search to public indices only.

Responses

Request samples 

# IP query example
curl -s -X GET \
    "https://app.netlas.io/api/host/23.215.0.136/" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

# Domain query example
curl -s -X GET \
    "https://app.netlas.io/api/host/example.com/" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

# Filtering output
curl -s -X GET \
"https://app.netlas.io/api/host/google.com/" \
  -G \
    --data-urlencode 'fields=whois.registrant.organization' \
    --data-urlencode 'source_type=include' \
  -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
Example
{
  • "type": "ip",
  • "ip": "23.215.0.136",
  • "ptr": [
    ],
  • "geo": {
    },
  • "privacy": {
    },
  • "organization": "Example Technologies, Inc.",
  • "domains": [
    ],
  • "domains_count": 2,
  • "whois": {
    },
  • "ports": [
    ],
  • "software": [],
  • "ioc": [
    ],
  • "source": [
    ]
}

Caller’s Host Summary

Retrieves the latest available data for the IP address of the client making the request.

Use this method to obtain information about your own IP address.

query Parameters
fields
Array of strings (fields)
Default: "*"
Examples: fields=* fields=ip fields=ptr[0],whois.abuse

You can control the amount of output data by specifying which fields to include or exclude in the response. Use the source_type parameter to select between include and exclude options.

source_type
string (source_type)
Default: "include"
Enum: "include" "exclude"

Specify fields and use source_type to choose between:

  • include to return only the specified fields
  • exclude to return all fields except the specified ones
public_indices_only
boolean (public_indices_only)
Default: false
Example: public_indices_only=true

By default, data is requested from both private and public indices, returning the most recent results. Use this query parameter to restrict the search to public indices only.

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/host/" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "type": "ip",
  • "ip": "23.215.0.136",
  • "ptr": [
    ],
  • "geo": {
    },
  • "privacy": {
    },
  • "organization": "Example Technologies, Inc.",
  • "domains": [
    ],
  • "domains_count": 2,
  • "whois": {
    },
  • "ports": [
    ],
  • "software": [],
  • "ioc": [
    ],
  • "source": [
    ]
}

Responses

Access continuously updated internet scan data collected by Netlas.

The same data available in the Netlas web interface via the Responses Search tool.

Responses Search

Searches for q in the selected indices and returns up to 20 search results, starting from the start+1 document.

❗️ This method allows retrieving only the first 10,000 search results.

Use it when the expected number of results is relatively low or to craft and refine a query. Use the Download endpoint to fetch results without pagination or quantity limitations.

query Parameters
q
required
string (q)
Examples:
  • q=host:example.com - responses for a specific host
  • q=ip:[1.1.1.1 TO 1.1.1.255] - responses for a specific IP range
  • q=protocol:ftp AND geo.country:VA - specific protocol and country

The query string used for searching. See Query Syntax for more details.

start
integer (start) [ 0 .. 9980 ]
Default: 0
Example: start=20

Use for pagination. Offset from the first search result to return.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

A list of indices where the search will be performed.

ℹ️ Unlike other search tools, Responses search does not have a default index.
If indices is not specified, the search is conducted using the latest publicly available internet scan data, which is updated in real time.

fields
Array of strings (fields)
Default: "*"
Examples: fields=* fields=ip fields=ptr[0],whois.abuse

You can control the amount of output data by specifying which fields to include or exclude in the response. Use the source_type parameter to select between include and exclude options.

source_type
string (source_type)
Default: "include"
Enum: "include" "exclude"

Specify fields and use source_type to choose between:

  • include to return only the specified fields
  • exclude to return all fields except the specified ones

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/responses/" \
    -G \
    --data-urlencode "q=host:example.com" \
    --data-urlencode "fields=ip,uri" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Responses Count

Counts the number of documents matching the search query q in the selected indices.

  • If there are fewer than 1,000 results, the method returns the exact count.
  • If there are more than 1,000 results, the count is estimated with an error margin not exceeding 3%.
query Parameters
q
required
string (q)
Example: q=ip:"23.192.0.0/11"

The query string used for searching. See Query Syntax for more details.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

A list of indices where the search will be performed.

ℹ️ Unlike other search tools, Responses search does not have a default index.
If indices is not specified, the search is conducted using the latest publicly available internet scan data, which is updated in real time.

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/responses_count/" \
    -G \
    --data-urlencode 'q=ip:"23.192.0.0/11"' \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "count": 123
}

Responses Download

Retrieves size search results matching the query q in the selected indices.

The Netlas SDK and CLI tool additionally include a download_all() method and an --all key that allow you to query all available results.

Request Body schema: application/json
required
q
required
string (q)

The query string used for searching. See Query Syntax for more details.

size
required
integer

Number of documents to download. Call corresponding Count endpoint to get a number of available documents.

indices
Array of integers (indices)

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

fields
required
Array of strings (fields)

You can control the amount of output data by specifying which fields to include or exclude in the response. Use the source_type parameter to select between include and exclude options.

source_type
required
string (source_type)
Enum: "include" "exclude"

Specify fields and use source_type to choose between:

  • include to return only the specified fields
  • exclude to return all fields except the specified ones
type
string
Default: "json"
Enum: "json" "csv"

Content type to download.

Responses

Request samples

Content type
application/json
{
  • "q": "ip:\"23.192.0.0/11\"",
  • "size": 100,
  • "fields": [
    ],
  • "source_type": "include"
}

Response samples

Content type
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Responses Facet Search

Searches for q in the selected indices and groups results by the facets field.

query Parameters
q
required
string (q)
Example: q=ip:"23.192.0.0/11"

The query string used for searching. See Query Syntax for more details.

facets
required
Array of strings (facets)
Example: facets=protocol

A list of fields to group search results by.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

A list of indices where the search will be performed.

ℹ️ Unlike other search tools, Responses search does not have a default index.
If indices is not specified, the search is conducted using the latest publicly available internet scan data, which is updated in real time.

size
integer (facet_search_size) [ 1 .. 1000 ]
Default: 100

Number of search results to return for each facet.

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/responses_facet/" \
    -G \
    --data-urlencode 'q=ip:"23.192.0.0/11"' \
    --data-urlencode 'facets=protocol' \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "aggregations": [
    ]
}

Domains

Information about domain names, their corresponding IP addresses, and other types of DNS records.

The same data available in the Netlas web interface via the DNS Search tool.

Domains Search

Searches for q in the selected indices and returns up to 20 search results, starting from the start+1 document.

❗️ This method allows retrieving only the first 10,000 search results.

Use it when the expected number of results is relatively low or to craft and refine a query. Use the Download endpoint to fetch results without pagination or quantity limitations.

query Parameters
q
required
string (q)
Examples:
  • q=domain:*.example.com a:* - subdomains of example.com with any A record
  • q=domain:/(.*\.)?paypal\.[a-z0-9-]*/ - domains and subdomains named "paypal" (regex)
  • q=ns:*.cloudflare.com - domains using Cloudflare name servers

The query string used for searching. See Query Syntax for more details.

start
integer (start) [ 0 .. 9980 ]
Default: 0
Example: start=20

Use for pagination. Offset from the first search result to return.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

fields
Array of strings (fields)
Default: "*"
Examples: fields=* fields=domain,a

You can control the amount of output data by specifying which fields to include or exclude in the response. Use the source_type parameter to select between include and exclude options.

source_type
string (source_type)
Default: "include"
Enum: "include" "exclude"

Specify fields and use source_type to choose between:

  • include to return only the specified fields
  • exclude to return all fields except the specified ones

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/domains/" \
    -G \
    --data-urlencode "q=domain:example.com" \
    --data-urlencode "fields=a,aaaa,ns,mx,txt" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Domains Count

Counts the number of documents matching the search query q in the selected indices.

  • If there are fewer than 1,000 results, the method returns the exact count.
  • If there are more than 1,000 results, the count is estimated with an error margin not exceeding 3%.
query Parameters
q
required
string (q)
Example: q=domain:*.example.com a:*

The query string used for searching. See Query Syntax for more details.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/domains_count/" \
    -G \
    --data-urlencode "q=domain:*.example.com a:*" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "count": 123
}

Domains Download

Retrieves size search results matching the query q in the selected indices.

The Netlas SDK and CLI tool additionally include a download_all() method and an --all key that allow you to query all available results.

Request Body schema: application/json
required
q
required
string (q)

The query string used for searching. See Query Syntax for more details.

size
required
integer

Number of documents to download. Call corresponding Count endpoint to get a number of available documents.

indices
Array of integers (indices)

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

fields
required
Array of strings (fields)

You can control the amount of output data by specifying which fields to include or exclude in the response. Use the source_type parameter to select between include and exclude options.

source_type
required
string (source_type)
Enum: "include" "exclude"

Specify fields and use source_type to choose between:

  • include to return only the specified fields
  • exclude to return all fields except the specified ones
type
string
Default: "json"
Enum: "json" "csv"

Content type to download.

Responses

Request samples

Content type
application/json
{
  • "q": "domain:*.example.com a:*",
  • "size": 100,
  • "fields": [
    ],
  • "source_type": "include"
}

Response samples

Content type
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Domains Facet Search

Searches for q in the selected indices and groups results by the facets field.

query Parameters
q
required
string (q)
Example: q=level:2

The query string used for searching. See Query Syntax for more details.

facets
required
Array of strings (facets)
Example: facets=zone

A list of fields to group search results by.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

size
integer (facet_search_size) [ 1 .. 1000 ]
Default: 100

Number of search results to return for each facet.

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/domains_facet/" \
    -G \
    --data-urlencode 'q=level:2' \
    --data-urlencode 'facets=zone' \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "aggregations": [
    ]
}

IP WHOIS

Provides information on IP address ownership, network provider details, contact information, and other WHOIS data.

The same data available in the Netlas web interface via the IP WHOIS Search tool.

IP WHOIS Search

Searches for q in the selected indices and returns up to 20 search results, starting from the start+1 document.

❗️ This method allows retrieving only the first 10,000 search results.

Use it when the expected number of results is relatively low or to craft and refine a query. Use the Download endpoint to fetch results without pagination or quantity limitations.

query Parameters
q
required
string (q)
Examples:
  • q=ip:23.215.0.136 - search for a specific IP address
  • q=net.cidr:1.1.1.0 net.net_size:255 - search for a specific CIDR range
  • q=net.organization:Mandiant - networks related to a specific organization

The query string used for searching. See Query Syntax for more details.

start
integer (start) [ 0 .. 9980 ]
Default: 0
Example: start=20

Use for pagination. Offset from the first search result to return.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

fields
Array of strings (fields)
Default: "*"
Examples: fields=* fields=ip fields=ptr[0],whois.abuse

You can control the amount of output data by specifying which fields to include or exclude in the response. Use the source_type parameter to select between include and exclude options.

source_type
string (source_type)
Default: "include"
Enum: "include" "exclude"

Specify fields and use source_type to choose between:

  • include to return only the specified fields
  • exclude to return all fields except the specified ones

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/whois_ip/" \
    -G \
    --data-urlencode "q=ip:23.215.0.136" \
    --data-urlencode "fields=net,asn" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "items": [
    ]
}

IP WHOIS Count

Counts the number of documents matching the search query q in the selected indices.

  • If there are fewer than 1,000 results, the method returns the exact count.
  • If there are more than 1,000 results, the count is estimated with an error margin not exceeding 3%.
query Parameters
q
required
string (q)
Example: q=net.country:VA

The query string used for searching. See Query Syntax for more details.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/whois_ip_count/" \
    -G \
    --data-urlencode "q=net.country:VA" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "count": 123
}

IP WHOIS Download

Retrieves size search results matching the query q in the selected indices.

The Netlas SDK and CLI tool additionally include a download_all() method and an --all key that allow you to query all available results.

Request Body schema: application/json
required
q
required
string (q)

The query string used for searching. See Query Syntax for more details.

size
required
integer

Number of documents to download. Call corresponding Count endpoint to get a number of available documents.

indices
Array of integers (indices)

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

fields
required
Array of strings (fields)

You can control the amount of output data by specifying which fields to include or exclude in the response. Use the source_type parameter to select between include and exclude options.

source_type
required
string (source_type)
Enum: "include" "exclude"

Specify fields and use source_type to choose between:

  • include to return only the specified fields
  • exclude to return all fields except the specified ones
type
string
Default: "json"
Enum: "json" "csv"

Content type to download.

Responses

Request samples

Content type
application/json
{
  • "q": "net.country:VA",
  • "size": 100,
  • "fields": [
    ],
  • "source_type": "include"
}

Response samples

Content type
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

IP WHOIS Facet Search

Searches for q in the selected indices and groups results by the facets field.

query Parameters
q
required
string (q)
Example: q=*

The query string used for searching. See Query Syntax for more details.

facets
required
Array of strings (facets)
Example: facets=net.country

A list of fields to group search results by.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

size
integer (facet_search_size) [ 1 .. 1000 ]
Default: 100

Number of search results to return for each facet.

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/whois_ip_facet/" \
    -G \
    --data-urlencode 'q=*' \
    --data-urlencode 'facets=net.country' \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "aggregations": [
    ]
}

Domain WHOIS

Information on domain ownership, registrar details, contact information, registration dates, expiration dates, and other WHOIS data.

The same data available in the Netlas web interface via the Domain WHOIS Search tool.

Domain WHOIS Search

Searches for q in the selected indices and returns up to 20 search results, starting from the start+1 document.

❗️ This method allows retrieving only the first 10,000 search results.

Use it when the expected number of results is relatively low or to craft and refine a query. Use the Download endpoint to fetch results without pagination or quantity limitations.

query Parameters
q
required
string (q)
Examples:
  • q=example.com - search for a specific domain
  • q=registrant.organization:"Meta Platforms" - domain registered to a specific organization
  • q=expiration_date:[2025-01-01 TO 2025-01-31] - domains expiring in 2023

The query string used for searching. See Query Syntax for more details.

start
integer (start) [ 0 .. 9980 ]
Default: 0
Example: start=20

Use for pagination. Offset from the first search result to return.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

fields
Array of strings (fields)
Default: "*"
Examples: fields=* fields=ip fields=ptr[0],whois.abuse

You can control the amount of output data by specifying which fields to include or exclude in the response. Use the source_type parameter to select between include and exclude options.

source_type
string (source_type)
Default: "include"
Enum: "include" "exclude"

Specify fields and use source_type to choose between:

  • include to return only the specified fields
  • exclude to return all fields except the specified ones

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/whois_domains/" \
    -G \
    --data-urlencode "q=domain:example.com" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Domain WHOIS Count

Counts the number of documents matching the search query q in the selected indices.

  • If there are fewer than 1,000 results, the method returns the exact count.
  • If there are more than 1,000 results, the count is estimated with an error margin not exceeding 3%.
query Parameters
q
required
string (q)
Example: q=registrant.organization:"Meta Platforms"

The query string used for searching. See Query Syntax for more details.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/whois_domains_count/" \
    -G \
    --data-urlencode 'q=registrant.organization:"Meta Platforms"' \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "count": 123
}

Domain WHOIS Download

Retrieves size search results matching the query q in the selected indices.

The Netlas SDK and CLI tool additionally include a download_all() method and an --all key that allow you to query all available results.

Request Body schema: application/json
required
q
required
string (q)

The query string used for searching. See Query Syntax for more details.

size
required
integer

Number of documents to download. Call corresponding Count endpoint to get a number of available documents.

indices
Array of integers (indices)

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

fields
required
Array of strings (fields)

You can control the amount of output data by specifying which fields to include or exclude in the response. Use the source_type parameter to select between include and exclude options.

source_type
required
string (source_type)
Enum: "include" "exclude"

Specify fields and use source_type to choose between:

  • include to return only the specified fields
  • exclude to return all fields except the specified ones
type
string
Default: "json"
Enum: "json" "csv"

Content type to download.

Responses

Request samples

Content type
application/json
{
  • "q": "registrant.organization:\"Meta Platforms\"",
  • "size": 100,
  • "fields": [
    ],
  • "source_type": "include"
}

Response samples

Content type
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Domain WHOIS Facet Search

Searches for q in the selected indices and groups results by the facets field.

query Parameters
q
required
string (q)
Example: q=level:2

The query string used for searching. See Query Syntax for more details.

facets
required
Array of strings (facets)
Example: facets=zone

A list of fields to group search results by.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

size
integer (facet_search_size) [ 1 .. 1000 ]
Default: 100

Number of search results to return for each facet.

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/whois_domains_facet/" \
    -G \
    --data-urlencode 'q=level:2' \
    --data-urlencode 'facets=zone' \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "aggregations": [
    ]
}

Certificates

A collection of x.509 certificates gathered from various sources.

The same data available in the Netlas web interface via the Certificates Search tool.

Certificates Search

Searches for q in the selected indices and returns up to 20 search results, starting from the start+1 document.

❗️ This method allows retrieving only the first 10,000 search results.

Use it when the expected number of results is relatively low or to craft and refine a query. Use the Download endpoint to fetch results without pagination or quantity limitations.

query Parameters
q
required
string (q)
Example: q=certificate.subject_dn:"example.com"

The query string used for searching. See Query Syntax for more details.

start
integer (start) [ 0 .. 9980 ]
Default: 0
Example: start=20

Use for pagination. Offset from the first search result to return.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

ℹ️ Netlas stores all collected certificates in a single default index.
This parameter is included for interface consistency but is not applicable to certificate-related endpoints.

fields
Array of strings (fields)
Default: "*"
Examples: fields=* fields=ip fields=ptr[0],whois.abuse

You can control the amount of output data by specifying which fields to include or exclude in the response. Use the source_type parameter to select between include and exclude options.

source_type
string (source_type)
Default: "include"
Enum: "include" "exclude"

Specify fields and use source_type to choose between:

  • include to return only the specified fields
  • exclude to return all fields except the specified ones

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/certs/" \
    -G \
    --data-urlencode "q=certificate.subject_dn:example.com" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Certificates Count

Counts the number of documents matching the search query q in the selected indices.

  • If there are fewer than 1,000 results, the method returns the exact count.
  • If there are more than 1,000 results, the count is estimated with an error margin not exceeding 3%.
query Parameters
q
required
string (q)
Example: q=certificate.subject_dn:"example.com"

The query string used for searching. See Query Syntax for more details.

indices
Array of integers (indices)
Default: ""
Examples: indices=1035 indices=1001,1021 indices=

ℹ️ Netlas stores all collected certificates in a single default index.
This parameter is included for interface consistency but is not applicable to certificate-related endpoints.

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/certs_count/" \
    -G \
    --data-urlencode 'q=certificate.subject_dn:example.com' \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "count": 123
}

Certificates Download

Retrieves size search results matching the query q in the selected indices.

The Netlas SDK and CLI tool additionally include a download_all() method and an --all key that allow you to query all available results.

Request Body schema: application/json
required
q
required
string (q)

The query string used for searching. See Query Syntax for more details.

size
required
integer

Number of documents to download. Call corresponding Count endpoint to get a number of available documents.

indices
Array of integers (indices)

A list of indice IDs to search in. If not provided, the search will be performed in the default (most relevant index).

Call indices endpoint to get the list of available indices.

fields
required
Array of strings (fields)

You can control the amount of output data by specifying which fields to include or exclude in the response. Use the source_type parameter to select between include and exclude options.

source_type
required
string (source_type)
Enum: "include" "exclude"

Specify fields and use source_type to choose between:

  • include to return only the specified fields
  • exclude to return all fields except the specified ones
type
string
Default: "json"
Enum: "json" "csv"

Content type to download.

Responses

Request samples

Content type
application/json
{
  • "q": "certificate.subject_dn:\"example.com\"",
  • "size": 100,
  • "fields": [
    ],
  • "source_type": "include"
}

Response samples

Content type
[
  • {},
  • {},
  • {},
  • {},
  • {
    }
]

Indices

Netlas organizes its data into indices. Each search tool has a dedicated set of indices with data collected on specific dates.

Responses search tool also provides access to private indices:

  • Public indices: regular Netlas indices available to all Netlas users.
  • Private indices: indices produced by using Private Scanner by you or shared with you by your teammates.

Get Indices

Retrieve a list of indices accessible to the user.

Responses

Request samples 

curl -X GET "https://app.netlas.io/api/indices/" \
    -H "content-type: application/json"

Response samples

Content type
application/json
[
  • {
    }
]

Mapping

Netlas stores collected data as JSON documents, organized into several data collections, such as Responses and Domains. Each data collection has its own mapping, which defines its document structure.

This group of methods provides access to the mapping of each data collection.

Get Mapping

Returns the field mapping for the default index in the {collection}.

Use this mapping to understand which fields are available and how they are typed, so you can craft precise search queries using Lucene Query Syntax.

Each field or subfield will include either a field_type or children property:

  • A field_type indicates that the field is a leaf node in the mapping tree.
  • A children property indicates a parent field that contains nested fields.

Example:

{
  "leaf": {
    "field_type": "type"
  },
  "parent": {
    "children": [
      {
        "leaf": {
          "field_type": "type"
        }
      }
    ]
  }
}

❗️Note: This endpoint returns the search mapping, which may slightly differ from the structure of actual search results. Refer to the response examples for each data collection to see how fields are represented in real-world data.

path Parameters
collection
required
string (dataCollectionType)
Enum: "responses" "domains" "whois_ip" "whois_domains" "certs"

The collection for which mapping should be retrieved.

Responses

Request samples 

curl -X GET \
    "https://app.netlas.io/api/mapping/responses/" \
    -H "content-type: application/json"

Response samples

Content type
application/json
Example
{
  • "ip": {
    },
  • "domain": {
    },
  • "host": {
    },
  • "host_type": {
    },
  • "path": {
    },
  • "port": {
    },
  • "prot4": {
    },
  • "prot7": {
    },
  • "protocol": {
    },
  • "ptr": {
    },
  • "referer": {
    },
  • "target": {
    },
  • "uri": {
    },
  • "certificate": {
    },
  • "cve": {
    },
  • "geo": {
    },
  • "jarm": {
    },
  • "isp": {
    },
  • "tag": {
    },
  • "whois": {
    },
  • "amqp": {
    },
  • "dns": {
    },
  • "elasticsearch": {
    },
  • "ftp": {
    },
  • "http": {
    },
  • "imap": {
    },
  • "memcached": {
    },
  • "modbus": {
    },
  • "mongodb": {
    },
  • "mqtt": {
    },
  • "mssql": {
    },
  • "mysql": {
    },
  • "netbios": {
    },
  • "ntp": {
    },
  • "oracle": {
    },
  • "pop3": {
    },
  • "postgres": {
    },
  • "raw_tcp": {
    },
  • "rdp": {
    },
  • "redis": {
    },
  • "s7": {
    },
  • "smb": {
    },
  • "smtp": {
    },
  • "snmp": {
    },
  • "socks": {
    },
  • "ssh": {
    },
  • "t3": {
    },
  • "telnet": {
    },
  • "vnc": {
    },
  • "scan_date": {
    },
  • "@timestamp": {
    },
  • "last_updated": {
    }
}

Get Facet Mapping

Returns the facet-specific field mapping for the {collection}.

This mapping includes only fields that are suitable for use in facet (group-by) searches. Not all fields in the regular mapping can be used for aggregation, so fields that are not aggregatable (e.g., large text fields, arrays) are excluded from the facet mapping.

Use this endpoint to discover which fields are available for grouping results in your search queries.

path Parameters
collection
required
string (dataCollectionType)
Enum: "responses" "domains" "whois_ip" "whois_domains" "certs"

The collection for which facet mapping should be retrieved.

Responses

Request samples 

curl -X GET \
    "https://app.netlas.io/api/mapping/responses/facet/" \
    -H "content-type: application/json"

Response samples

Content type
application/json
Example
{
  • "ip": {
    },
  • "domain": {
    },
  • "host": {
    },
  • "host_type": {
    },
  • "path": {
    },
  • "port": {
    },
  • "prot4": {
    },
  • "prot7": {
    },
  • "protocol": {
    },
  • "ptr": {
    },
  • "referer": {
    },
  • "target": {
    },
  • "uri": {
    },
  • "certificate": {
    },
  • "cve": {
    },
  • "geo": {
    },
  • "jarm": {
    },
  • "isp": {
    },
  • "tag": {
    },
  • "whois": {
    },
  • "amqp": {
    },
  • "dns": {
    },
  • "elasticsearch": {
    },
  • "ftp": {
    },
  • "http": {
    },
  • "imap": {
    },
  • "memcached": {
    },
  • "modbus": {
    },
  • "mongodb": {
    },
  • "mqtt": {
    },
  • "mssql": {
    },
  • "mysql": {
    },
  • "netbios": {
    },
  • "ntp": {
    },
  • "oracle": {
    },
  • "pop3": {
    },
  • "postgres": {
    },
  • "raw_tcp": {
    },
  • "rdp": {
    },
  • "redis": {
    },
  • "s7": {
    },
  • "smb": {
    },
  • "smtp": {
    },
  • "snmp": {
    },
  • "socks": {
    },
  • "ssh": {
    },
  • "t3": {
    },
  • "telnet": {
    },
  • "vnc": {
    },
  • "scan_date": {
    },
  • "@timestamp": {
    },
  • "last_updated": {
    }
}

Discovery

The Attack Surface Discovery tool helps explore and analyze relationships between internet entities such as IP addresses, domain names, networks, WHOIS records, and more.

This group of endpoints is used by the Discovery tool in the Netlas web app.

Searches for a Node

Retrieve a list of available searches for the specified node, defined by node_value and node_type.

Request Body schema: application/json
required
node_type
required
string (node_type)
Enum: "address" "as_name" "asn" "dns_txt" "domain" "email" "favicon" "http_tracker" "ip" "ip-range" "jarm" "network_name" "organization" "person" "phone" "text"

The type of the node(s).

node_value
required
string (node_value)

A value of the node.

Responses

Request samples

Content type
application/json
{
  • "node_type": "domain",
  • "node_value": "example.com"
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Perform a Node Search

Execute a search using search_field_id for a node specified by node_value and node_type, and retrieve the corresponding results.

header Parameters
X-Count-Id
required
string (X-Count-Id)
Example: 99ec3869b238d440bffc2c6e7b4c8dc3f98cdd9f6b3106d1350cf3c8c0af1837e2942a04780e223b215eb8b663cf5353

Perform a /api/discovery/node_count request to get the X-Count-Id.

Request Body schema: application/json
required
node_type
required
string (node_type)
Enum: "address" "as_name" "asn" "dns_txt" "domain" "email" "favicon" "http_tracker" "ip" "ip-range" "jarm" "network_name" "organization" "person" "phone" "text"

The type of the node(s).

node_value
required
string (node_value)

A value of the node.

search_field_id
required
integer (search_field_id)

The ID of the search type.

Responses

Request samples

Content type
application/json
{
  • "node_type": "domain",
  • "node_value": "example.com",
  • "search_field_id": 29
}

Response samples

Content type
application/json
{
  • "aggregations": [
    ]
}

Searches for a Group

Retrieve a list of available searches for a group of nodes, where each node is specified in node_value and must be of type node_type.

⚠️ Retrieving results for large groups may take significant time.

Request Body schema: application/json
required
node_type
required
string (node_type)
Enum: "address" "as_name" "asn" "dns_txt" "domain" "email" "favicon" "http_tracker" "ip" "ip-range" "jarm" "network_name" "organization" "person" "phone" "text"

The type of the node(s).

node_value
required
Array of strings (node_value)

A list of nodes.

Responses

Request samples

Content type
application/json
{
  • "node_type": "domain",
  • "node_value": [
    ]
}

Response samples

Content type
application/x-ndjson
"{ ... }\n{ ... }\n{ ... }\n"

Perform a Group Search

Execute a search using search_field_id for a group of nodes specified in node_value, and retrieve the corresponding results.

⚠️ Retrieving results for large groups may take significant time.

header Parameters
X-Count-Id
required
string (X-Count-Id)
Example: 99ec3869b238d440bffc2c6e7b4c8dc3f98cdd9f6b3106d1350cf3c8c0af1837e2942a04780e223b215eb8b663cf5353

Perform a /api/discovery/group_of_nodes_count request to get the X-Count-Id.

Request Body schema: application/json
required
node_type
required
string (node_type)
Enum: "address" "as_name" "asn" "dns_txt" "domain" "email" "favicon" "http_tracker" "ip" "ip-range" "jarm" "network_name" "organization" "person" "phone" "text"

The type of the node(s).

node_value
required
Array of strings (node_value)

A list of nodes.

search_field_id
required
integer (search_field_id)

The ID of the search type.

Responses

Request samples

Content type
application/json
{
  • "node_type": "domain",
  • "node_value": [
    ],
  • "search_field_id": 29
}

Response samples

Content type
application/x-ndjson
"{ ... }\n{ ... }\n{ ... }\n"

Check Search Status

Retrieve the current status of an ongoing group search operation: fetching available searches for a group or executing a search for a group.

path Parameters
stream-id
required
string (X-Stream-Id)
Example: 99ec3869b238d440bffc2c6e7b4c8dc3c63309fe08d50c704cba0c91acfedc63

The unique identifier of a stream used to track the progress of a search.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Scanner

The Netlas Private Scanner performs non-intrusive scans of internet-connected assets.

This group of endpoints is used by the Private Scanner tool in the Netlas web app.

Get Scans

Retrieve a list of private scans available to the user.

query Parameters
own_scans_only
boolean
Default: true

Filter to return only the scans owned by the user

Responses

Request samples 

curl -s -X GET "https://app.netlas.io/api/scanner/" \
    -H "content-type: application/json" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
[
  • {
    }
]

Create Scan

Create and initiate a new private scan.

Request Body schema: application/json
required
Array of IPv4 (string) or Domain (string) or CIDR (string) (targets)

A list of targets for the scan.
Valid targets include IP addresses, domain names, and CIDR ranges.

label
string or null (scan_label)

Descriptive label for the scan.

Responses

Request samples

Content type
application/json
{
  • "targets": [
    ],
  • "label": "My Private Scan"
}

Response samples

Content type
application/json
[
  • {
    }
]

Change Scan Priority

Modify the priority of a private scan with id in the processing queue by shifting it shift positions.

ℹ️ This adjustment applies only to scans with the Pending status. Scans that are already scheduled or in progress will not be affected.

Request Body schema: application/json
required
id
integer (scan_id)

Unique identifier for the scan.

shift
integer (shift)

The number of positions to adjust the scan's priority in the queue.

  • A negative value (e.g., -2) moves the scan closer to the front, prioritizing it for earlier execution.
  • A positive value (e.g., +3) moves the scan further back, delaying its execution.

Responses

Request samples

Content type
application/json
{
  • "id": 123,
  • "shift": -2
}

Response samples

Content type
application/json
[
  • {
    }
]

Get Scan

Retrieve detailed information about a private scan using its id.

path Parameters
id
required
integer (scan_id)
Example: 123

Unique identifier for the scan.

Responses

Request samples 

if [ -z "$1" ]; then
    echo "Error: Pass scan ID as an argument"
    exit 1
fi

curl -X GET "https://app.netlas.io/api/scanner/$1/" \
    -H "content-type: application/json" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "id": 4336,
  • "label": "23.215.0.136, example.com",
  • "targets": [
    ],
  • "scan_started_dt": "2025-03-11T11:49:11Z",
  • "scan_ended_dt": "2025-03-11T11:51:20Z",
  • "scan_progress": [
    ],
  • "created_dt": "2025-03-11T10:18:10.315185Z",
  • "index_id": 4701,
  • "saved_graph": null,
  • "estimated_time_to_complete": 0,
  • "queue_position": null,
  • "count": 14,
  • "owner": {
    },
  • "is_scan_from_team": false,
  • "status": "done"
}

Update Scan

Update the label of a private scan using its id.

path Parameters
id
required
integer (scan_id)
Example: 123

Unique identifier for the scan.

Request Body schema: application/json
required

The new label for the scan

label
string or null (scan_label)

New label for the scan

Responses

Request samples

Content type
application/json
{
  • "label": "Updated Scan Label"
}

Response samples

Content type
application/json
{
  • "id": 4336,
  • "label": "23.215.0.136, example.com",
  • "targets": [
    ],
  • "scan_started_dt": "2025-03-11T11:49:11Z",
  • "scan_ended_dt": "2025-03-11T11:51:20Z",
  • "scan_progress": [
    ],
  • "created_dt": "2025-03-11T10:18:10.315185Z",
  • "index_id": 4701,
  • "saved_graph": null,
  • "estimated_time_to_complete": 0,
  • "queue_position": null,
  • "count": 14,
  • "owner": {
    },
  • "is_scan_from_team": false,
  • "status": "done"
}

Delete Scan

Permanently remove a private scan using its id.

path Parameters
id
required
integer (scan_id)
Example: 123

Unique identifier for the scan.

Responses

Request samples 

if [ -z "$1" ]; then
    echo "Error: Pass scan ID as an argument"
    exit 1
fi

curl -X 'DELETE' "https://app.netlas.io/api/scanner/$1/" \
    -H "content-type: application/json" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "type": "authorization_required",
  • "title": "Authorization required",
  • "detail": "You have to be signed in to perform this operation."
}

Bulk Delete Scans

Delete multiple private scans using their respective id values.

Request Body schema: application/json
required

The list of scan IDs to delete

ids
Array of integers (scan_id)

List of scan IDs to delete

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": "Validation error."
}

Datastore

The Netlas Datastore API provides access to a wide range of network-related datasets.

Use these endpoints to access the Netlas Datastore.

Get Products

Retrieve a list of published datasets available in the Netlas Datastore.

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/datastore/products/" \
    -H "content-type: application/json"

Response samples

Content type
application/json
[
  • {
    }
]

Get Product

Retrieve details of a specific dataset from the Netlas Datastore.

path Parameters
id
required
integer (product_id)
Examples: 28 80 241 242 279 280

A unique identifier for the product.

Datasets belong to Product objects. A product can include one or multiple datasets.

Responses

Request samples 

curl -s -X GET \
    "https://app.netlas.io/api/datastore/products/23/" \
    -H "content-type: application/json"

Response samples

Content type
application/json
{
  • "id": 23,
  • "description": "Known domain names with A, MX, NS, CNAME and TXT records. ",
  • "datasets": [
    ],
  • "data_type": {
    },
  • "data_category": {
    },
  • "count": 2475195512,
  • "size": {
    },
  • "name": "whole_dns_registry",
  • "pretty_name": "Forward DNS (fDNS)",
  • "fields": [
    ],
  • "price": "990.00",
  • "priority": 20,
  • "meta_data": {}
}

Users

User profile data and settings.

Get User Profile

Retrieve profile details of the currently authenticated user.

Responses

Request samples 

curl -X GET "https://app.netlas.io/api/users/current/" \
    -H "content-type: application/json" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "api_key": {
    },
  • "email": "[email protected]",
  • "first_name": "string",
  • "last_name": "string",
  • "account_category": "company",
  • "occupation": "string",
  • "occupation_details": "string",
  • "is_welcome_tour_passed": true,
  • "plan": { },
  • "plan_active_until": "2019-08-24",
  • "next_plan": { },
  • "is_next_plan_paid": true,
  • "next_plan_paid_period": "string",
  • "referral_code": "string",
  • "bonuses": 0,
  • "notifications": [
    ],
  • "teams": [
    ],
  • "is_recurring": true,
  • "is_authenticated_via_social": true,
  • "referral_link_usage_amount": 0,
  • "profession": "string",
  • "usage_purpose": "string"
}

Update User Profile

Modify the profile details of the currently authenticated user.

Request Body schema: application/json
required
first_name
required
string

The user's first name.

last_name
string

The user's last name.

Responses

Request samples

Content type
application/json
Example

name and last name

{
  • "first_name": "John",
  • "last_name": "Doe"
}

Response samples

Content type
application/json
{
  • "api_key": {
    },
  • "email": "[email protected]",
  • "first_name": "string",
  • "last_name": "string",
  • "account_category": "company",
  • "occupation": "string",
  • "occupation_details": "string",
  • "is_welcome_tour_passed": true,
  • "plan": { },
  • "plan_active_until": "2019-08-24",
  • "next_plan": { },
  • "is_next_plan_paid": true,
  • "next_plan_paid_period": "string",
  • "referral_code": "string",
  • "bonuses": 0,
  • "notifications": [
    ],
  • "teams": [
    ],
  • "is_recurring": true,
  • "is_authenticated_via_social": true,
  • "referral_link_usage_amount": 0,
  • "profession": "string",
  • "usage_purpose": "string"
}

Get User Counters

Retrieve the currently authenticated user's profile counters, including request limits and Netlas Coins balance.

Responses

Request samples 

curl -X GET "https://app.netlas.io/api/users/profile_data/" \
    -H "content-type: application/json" \
    -H "Authorization: Bearer $NETLAS_API_KEY"

Response samples

Content type
application/json
{
  • "requests_left": {
    },
  • "coins": {
    },
  • "scan_coins": {
    }
}