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": {