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.1 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.

⚠️ For tools that still expect OpenAPI 3.0, use the OpenAPI 3.0 JSON, for example with Thunder Client, RapidAPI for Mac (Paw), and other older OpenAPI-based import and code generation workflows.

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 strings (indices)
Default: ""
Examples:
  • indices= - Search in the latest data available
  • indices=2025-09-24,2025-09-02 - Search in specific indices
  • indices=1764230724-u6lrerkpx - Search in private index

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 strings (indices)
Default: ""
Examples:
  • indices= - Search in the latest data available
  • indices=2025-09-24,2025-09-02 - Search in specific indices
  • indices=1764230724-u6lrerkpx - Search in private index

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 strings (indices)

A list of indice labels 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"

Download output format.

  • json: JSON array output.
  • csv: CSV text output in the response body.

Note: the API may still respond with Content-Type: application/json for CSV output, and Accept: text/csv may return 406. Use request field type: csv to request CSV.

Responses

Request samples

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

Response samples

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

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 strings (indices)
Default: ""
Examples:
  • indices= - Search in the latest data available
  • indices=2025-09-24,2025-09-02 - Search in specific indices
  • indices=1764230724-u6lrerkpx - Search in private index

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 strings (indices)
Default: ""
Examples: indices=2025-09-24,2025-09-02 indices=

A list of indice labels 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 strings (indices)
Default: ""
Examples: indices=2025-09-24,2025-09-02 indices=

A list of indice labels 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 strings (indices)

A list of indice labels 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"

Download output format.

  • json: JSON array output.
  • csv: CSV text output in the response body.

Note: the API may still respond with Content-Type: application/json for CSV output, and Accept: text/csv may return 406. Use request field type: csv to request CSV.

Responses

Request samples

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

Response samples

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

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 strings (indices)
Default: ""
Examples: indices=2025-09-24,2025-09-02 indices=

A list of indice labels 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 strings (indices)
Default: ""
Examples: indices=2025-09-24,2025-09-02 indices=

A list of indice labels 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:212.77.12.64" \
    --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 strings (indices)
Default: ""
Examples: indices=2025-09-24,2025-09-02 indices=

A list of indice labels 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 strings (indices)

A list of indice labels 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"

Download output format.

  • json: JSON array output.
  • csv: CSV text output in the response body.

Note: the API may still respond with Content-Type: application/json for CSV output, and Accept: text/csv may return 406. Use request field type: csv to request CSV.

Responses

Request samples

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

Response samples

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

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 strings (indices)
Default: ""
Examples: indices=2025-09-24,2025-09-02 indices=

A list of indice labels 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 strings (indices)
Default: ""
Examples: indices=2025-09-24,2025-09-02 indices=

A list of indice labels 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 strings (indices)
Default: ""
Examples: indices=2025-09-24,2025-09-02 indices=

A list of indice labels 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 strings (indices)

A list of indice labels 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"

Download output format.

  • json: JSON array output.
  • csv: CSV text output in the response body.

Note: the API may still respond with Content-Type: application/json for CSV output, and Accept: text/csv may return 406. Use request field type: csv to request CSV.

Responses

Request samples

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

Response samples

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

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 strings (indices)
Default: ""
Examples: indices=2025-09-24,2025-09-02 indices=

A list of indice labels 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 strings (indices)
Default: ""
Examples: indices=2025-09-24,2025-09-02 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 strings (indices)
Default: ""
Examples: indices=2025-09-24,2025-09-02 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 strings (indices)

A list of indice labels 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"

Download output format.

  • json: JSON array output.
  • csv: CSV text output in the response body.

Note: the API may still respond with Content-Type: application/json for CSV output, and Accept: text/csv may return 406. Use request field type: csv to request CSV.

Responses

Request samples

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

Response samples

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

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
{
  • "http": {
    },
  • "ip": {
    }
}

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
{
  • "http": {
    },
  • "ip": {
    }
}

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
"{\"search_field\": \"TXT records for domain\", \"count\": 2, \"preview\": [\"_k2n1y4vw3qtb4skdx9e7dxt97qrmmq9\", \"v=spf1 -all\"], \"search_field_id\": 32, \"is_too_much_docs\": false, \"node_types\": {\"dns_txt\": 3}}\n{\"search_field\": \"NS servers for domain\", \"count\": 2, \"preview\": [\"elliott.ns.cloudflare.com\", \"hera.ns.cloudflare.com\"], \"search_field_id\": 30, \"is_too_much_docs\": false, \"node_types\": {\"domain\": 1}}\n{\"search_field\": \"A records for domain\", \"count\": 16, \"preview\": [\"8.6.112.0\", \"8.6.112.6\", \"8.6.112.8\", \"8.6.112.10\", \"8.47.69.0\"], \"search_field_id\": 29, \"is_too_much_docs\": false, \"node_types\": {\"ip\": 0}}\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
"{\"node_key\": \"example.org\", \"aggregations\": [{\"is_valid\": true, \"node_value\": \"104.18.2.24\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"104.18.3.24\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"40.89.128.172\", \"node_type\": \"ip\"}]}\n{\"node_key\": \"example.com\", \"aggregations\": [{\"is_valid\": true, \"node_value\": \"104.18.27.120\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"104.18.26.120\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.6.112.0\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.47.69.0\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.47.69.10\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.6.112.10\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.74.138.66\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.88.251.189\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.88.128.4\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.88.198.69\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.88.198.68\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.47.69.8\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.6.112.8\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.6.112.6\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.47.69.6\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"23.227.38.74\", \"node_type\": \"ip\"}]}\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
Any of
name
required
string (scan_name)

Descriptive label for the scan.

agent_id
integer (agent_id)

Identifier of the scanner agent to use for the scan.

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.

saved_graph_id
string

Identifier of the saved attack surface graph to scan.

version
integer

Saved graph version.

Responses

Request samples

Content type
application/json
{
  • "name": "My Private Scan",
  • "agent_id": 5,
  • "targets": [
    ],
  • "saved_graph_id": "string",
  • "version": 0
}

Response samples

Content type
application/json
[
  • {
    }
]

Get Scanner Agents

Retrieve the list of scanner agents available for initiating private scans from different geolocations.

Responses

Request samples 

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

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": 89,
  • "name": "Test Scan",
  • "label": "1764230724-u6lrerkpx",
  • "targets": [
    ],
  • "created_at": "2025-11-27T08:05:24.518270Z",
  • "owner": {},
  • "is_scan_from_team": false,
  • "mode": "top_tcp_ports",
  • "state": "done",
  • "agent": {
    }
}

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

name
string (scan_name)

New label for the scan

Responses

Request samples

Content type
application/json
{
  • "name": "Updated scan name"
}

Response samples

Content type
application/json
{
  • "id": 89,
  • "name": "Test Scan",
  • "label": "1764230724-u6lrerkpx",
  • "targets": [
    ],
  • "created_at": "2025-11-27T08:05:24.518270Z",
  • "owner": {},
  • "is_scan_from_team": false,
  • "mode": "top_tcp_ports",
  • "state": "done",
  • "agent": {
    }
}

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."
}

Get Scan Report

Retrieve the JSON report generated for 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 -s -X GET "https://app.netlas.io/api/scanner/$1/report/" \
    -H "Authorization: Bearer $NETLAS_API_KEY" \
    -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "id": 1001,
  • "name": "Example scan report",
  • "created_at": "2026-04-10T12:00:00Z",
  • "scan_id": 123,
  • "scope": [
    ],
  • "saved_graph": null,
  • "mode": "top_tcp_ports",
  • "agent": {
    },
  • "responses": [
    ],
  • "cve": {
    }
}

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
required
integer (scan_id)

Unique identifier for the scan.

shift
required
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
[
  • {
    }
]

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/115/" \
    -H "content-type: application/json"

Response samples

Content type
application/json
{
  • "id": 115,
  • "description": "Known domain names with A, MX, NS, CNAME and TXT records.",
  • "datasets": [
    ],
  • "name": "fdns",
  • "pretty_name": "Forward DNS (fDNS)"
}

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
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 user profile counters, including request limits and Netlas Coins balance. This endpoint is public, but authenticated requests may return additional counters.

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": {
    }
}
\n\n","status_line":"200 OK","title":"Example Domain","content_length":-1},"scan_date":"2025-02-13"}},"ResponsesSearch":{"type":"object","required":["items"],"properties":{"items":{"type":"array","description":"0 to 20 documents that match the search query","items":{"type":"object","properties":{"highlight":{"$ref":"#/components/schemas/highlight"},"data":{"$ref":"#/components/schemas/ResponseDocument"}}}}}},"ACCESS_DENIED_SCHEMA":{"type":"object","title":"Access Denied","required":["type","detail"],"properties":{"type":{"type":"string","enum":["access_denied"]},"title":{"type":"string","description":"Short error title.","example":"Access Denied"},"detail":{"type":"string","description":"Description of the occurred error.","example":"Your current subscription plan does not allow you to make this request."}}},"Count":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","description":"Number of documents that match the search query","example":123}}},"DownloadPayload":{"type":"object","required":["q","size","fields","source_type"],"properties":{"q":{"$ref":"#/components/schemas/q"},"size":{"type":"integer","description":"Number of documents to download. Call corresponding __Count__ endpoint to get a number of available documents.","example":1000},"indices":{"$ref":"#/components/schemas/indices","example":["2025-09-24","2025-09-02"]},"fields":{"$ref":"#/components/schemas/fields"},"source_type":{"$ref":"#/components/schemas/source_type"},"type":{"type":"string","description":"Download output format.\n\n- `json`: JSON array output.\n- `csv`: CSV text output in the response body.\n\nNote: the API may still respond with `Content-Type: application/json` for CSV output,\nand `Accept: text/csv` may return `406`. Use request field `type: csv` to request CSV.\n","enum":["json","csv"],"default":"json"}}},"ResponsesDownloadJSON":{"type":"array","items":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResponseDocument"}}}},"DownloadCSV":{"type":"string","description":"CSV text content returned by download endpoints when `type: csv` is requested.\n"},"UNAUTHORIZED_SCHEMA":{"type":"object","title":"Authorization Required","required":["detail"],"properties":{"type":{"type":"string","enum":["authorization_required"]},"title":{"type":"string","enum":["Authorization required"]},"detail":{"type":"string","enum":["You have to be signed in to perform this operation."]}}},"facets":{"type":"array","items":{"$ref":"#/components/schemas/field"},"description":"A list of fields to group search results by.\n","example":["geo.country"]},"facet_search_size":{"type":"integer","description":"Number of search results to return for each facet.\n","default":100,"minimum":1,"maximum":1000},"FacetSearchResults":{"type":"object","properties":{"aggregations":{"type":"array","description":"A list of aggregated search results.","items":{"type":"object","properties":{"key":{"type":"array","items":{"type":"string"},"description":"Aggregation key","example":["any_valid_key"]},"doc_count":{"type":"integer","description":"A number of document with the given key in the search results","example":1675}}}}}},"DomainsSearch":{"type":"object","required":["items"],"properties":{"items":{"type":"array","description":"0 to 20 documents that match the search query","items":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DomainsDocument"}}}}}},"DomainsDownloadJSON":{"type":"array","items":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DomainsDocument"}}}},"IpWhoisSearch":{"type":"object","required":["items"],"properties":{"items":{"type":"array","description":"0 to 20 documents that match the search query","items":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IpWhoisDocument"}}}}}},"IpWhoisDownloadJSON":{"type":"array","items":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IpWhoisDocument"}}}},"DomainWhoisDocument":{"type":"object","description":"WHOIS information for a domain","example":{"server":"whois.iana.org","last_updated":"2024-05-05T01:45:12.744Z","extension":"com","@timestamp":"2024-05-05T01:45:12.744Z","punycode":"example.com","level":2,"zone":"com","domain":"example.com","name":"example","raw":"Raw WHOIS data in the form of a string will be here.\n\nThe rest of the document contains the same data in parsed form.","created_date":"1992-01-01T00:00:00.000Z","extracted_domain":"example.com"}},"DomainWhoisSearch":{"type":"object","required":["items"],"properties":{"items":{"type":"array","description":"0 to 20 documents that match the search query","items":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DomainWhoisDocument"}}}}}},"DomainWhoisDownloadJSON":{"type":"array","items":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DomainWhoisDocument"}}}},"CertificateDocument":{"type":"object","description":"X.509 certificate information","example":{"issuer_dn":"C=US, O=DigiCert Inc, CN=DigiCert Global G3 TLS ECC SHA384 2020 CA1","fingerprint_md5":"c33979ff8bc19a94820d6804b3681881","chain":[{"issuer_dn":"C=US, O=DigiCert Inc, OU=www.digicert.com, CN=DigiCert Global Root G3","fingerprint_md5":"bf44da68b5abcb0a48c8471806ff9706","redacted":false,"signature":{"valid":false,"signature_algorithm":{"name":"ECDSA-SHA384","oid":"1.2.840.10045.4.3.3"},"value":"MGUCMH4mWG7uiOwM3RVB7nq4mZlw0WJlT6AgnkexW8GyZzEdzHJ6ryJyQEJuZYT+h0sPGQIxAOa/1q40h1s/Z8cdqG/VEni15ocxRKldxrh4zM/v1DJYEf86hQY8HYRv0/X52jMcpA==","self_signed":false},"subject":{"country":["US"],"organization":["DigiCert Inc"],"common_name":["DigiCert Global G3 TLS ECC SHA384 2020 CA1"]},"serial_number":"14626237344301700912191253757342652550","version":3,"issuer":{"country":["US"],"organization":["DigiCert Inc"],"common_name":["DigiCert Global Root G3"],"organizational_unit":["www.digicert.com"]},"fingerprint_sha256":"0587d6bd2819587ab90fb596480a5793bd9f7506a3eace73f5eab366017fe259","tbs_noct_fingerprint":"b01920744bbb76c9ab053e01e07b7e050e473d20f79f7bea435fafe43c9d242f","extensions":{"crl_distribution_points":["http://crl3.digicert.com/DigiCertGlobalRootG3.crl"],"subject_key_id":"8a23eb9e6bd7f9375df96d2139769aa167de10a8","certificate_policies":[{"id":"2.16.840.1.114412.2.1"},{"id":"2.23.140.1.1"},{"id":"2.23.140.1.2.1"},{"id":"2.23.140.1.2.2"},{"id":"2.23.140.1.2.3"}],"authority_key_id":"b3db48a4f9a1c5d8ae3641cc1163696229bc4bc6","key_usage":{"digital_signature":true,"certificate_sign":true,"crl_sign":true,"value":97},"authority_info_access":{"issuer_urls":["http://cacerts.digicert.com/DigiCertGlobalRootG3.crt"],"ocsp_urls":["http://ocsp.digicert.com"]},"basic_constraints":{"max_path_len":0,"is_ca":true},"extended_key_usage":{"client_auth":true,"server_auth":true}},"tbs_fingerprint":"b01920744bbb76c9ab053e01e07b7e050e473d20f79f7bea435fafe43c9d242f","subject_dn":"C=US, O=DigiCert Inc, CN=DigiCert Global G3 TLS ECC SHA384 2020 CA1","fingerprint_sha1":"9577f91fe86c27d9912129730e8166373fc2eeb8","signature_algorithm":{"name":"ECDSA-SHA384","oid":"1.2.840.10045.4.3.3"},"spki_subject_fingerprint":"a7cb399df47e982018276c3397790bdef648e6d87b2f7b90d551f719ac6098c4","validity":{"length":315532799,"start":"2021-04-14T00:00:00Z","end":"2031-04-13T23:59:59Z"},"validation_level":"EV"}],"redacted":false,"src":"https://www.example.com:443/","signature":{"valid":false,"signature_algorithm":{"name":"ECDSA-SHA384","oid":"1.2.840.10045.4.3.3"},"value":"MGUCMQD5poJGU9tv5Vj67hq8/Jobt+9QMmo3wrCWtcPhem1PtAv4PTf4ED8VQSjd0PWLPfsCMGRjeOGy4sBbulawNu1f9DDGnqQ2wriOHX9GO9X/brSzFDAz8Yzu3T5PS4/Yv5jXZQ==","self_signed":false},"subject":{"country":["US"],"province":["California"],"organization":["Internet Corporation for Assigned Names and Numbers"],"locality":["Los Angeles"],"common_name":["*.example.com"]},"serial_number":"14416812407440461216471976375640436634","version":3,"issuer":{"country":["US"],"organization":["DigiCert Inc"],"common_name":["DigiCert Global G3 TLS ECC SHA384 2020 CA1"]},"fingerprint_sha256":"455943cf819425761d1f950263ebf54755d8d684c25535943976f488bc79d23b","tbs_noct_fingerprint":"bc8ace8a15de0d8136c6f642e1d1e367a3dd38d5534e3fc4f52c5ee6b86cb25d","extensions":{"crl_distribution_points":["http://crl3.digicert.com/DigiCertGlobalG3TLSECCSHA3842020CA1-2.crl","http://crl4.digicert.com/DigiCertGlobalG3TLSECCSHA3842020CA1-2.crl"],"subject_key_id":"f0c16a320decdac7ea8fcd0d6d191259d1be72ed","certificate_policies":[{"cps":["http://www.digicert.com/CPS"],"id":"2.23.140.1.2.2"}],"authority_key_id":"8a23eb9e6bd7f9375df96d2139769aa167de10a8","key_usage":{"key_agreement":true,"digital_signature":true,"value":17},"subject_alt_name":{"dns_names":["*.example.com","example.com"]},"signed_certificate_timestamps":[{"log_id":"DleUvPOuqT4zGyyZB7P3kN+bwj1xMiXdIaklrGHFTiE=","signature":"BAMARTBDAh8kFw9aTHzSKTu4thbo4a81i8ng2Y5HZFdz26+IU8fpAiBS265R6cchPlQ1Yl98EFGrfW1QaLtkNNKuszR/jPVVrg==","version":0,"timestamp":1736902885},{"log_id":"ZBHEbKQS7KeJHKICLgC8q08oB9QeNSer6v7VA8l9zfA=","signature":"BAMARjBEAiBwrujYB4VdUL4n/xuwR6u3IjBh/I3XIf8cuC862JXrFwIgcjBTLw4RoOLGJtTLKwxlXnXMKROHjdEbmXBRplscCXI=","version":0,"timestamp":1736902885},{"log_id":"SZybad4dfOz8Nt7Nh2SmuFuvCoeAGdFVUvvp6ynd+MM=","signature":"BAMARzBFAiBoWHrvIRDaXCCbdfXqfaJaMRAUgjZvZ+k420FWJtlVbAIhAPmmyqNcNiwgRvWHKHRLxsE3c7i7awD3OKwoiViNmDzC","version":0,"timestamp":1736902885}],"authority_info_access":{"issuer_urls":["http://cacerts.digicert.com/DigiCertGlobalG3TLSECCSHA3842020CA1-2.crt"],"ocsp_urls":["http://ocsp.digicert.com"]},"basic_constraints":{"is_ca":false},"extended_key_usage":{"client_auth":true,"server_auth":true}},"tbs_fingerprint":"ad7d5aa4244532a22369dfa25a851e180cb34a39d90efba98022f0f9832e0bd9","names":["*.example.com","example.com"],"subject_dn":"C=US, ST=California, L=Los Angeles, O=Internet Corporation for Assigned Names and Numbers, CN=*.example.com","fingerprint_sha1":"310db7af4b2bc9040c8344701aca08d0c69381e3","signature_algorithm":{"name":"ECDSA-SHA384","oid":"1.2.840.10045.4.3.3"},"spki_subject_fingerprint":"9d77c9a308deb7b5d91be7d8d5e10587bd9381a70913cfad1883b9bdcd825d43","validity":{"length":31622399,"start":"2025-01-15T00:00:00Z","end":"2026-01-15T23:59:59Z"},"validation_level":"OV"}},"CertificateSearch":{"type":"object","required":["items"],"properties":{"items":{"type":"array","description":"0 to 20 documents that match the search query","items":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CertificateDocument"}}}}}},"CertificateDownloadJSON":{"type":"array","items":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CertificateDocument"}}}},"indiceId":{"type":"integer","description":"Unique identifier for the index.","examples":[1001,1021,1035]},"dataCollectionType":{"type":"string","enum":["responses","domains","whois_ip","whois_domains","certs"],"description":"Type of the data collection."},"indice":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/indiceId"},"name":{"type":"string","description":"System-generated name of the index."},"label":{"type":["string","null"],"description":"Unique text identifier for the index."},"scan_started_at":{"type":"string","format":"date-time","description":"Timestamp indicating when data collection started."},"scan_ended_at":{"type":"string","format":"date-time","description":"Timestamp indicating when data collection was completed."},"type":{"$ref":"#/components/schemas/dataCollectionType"},"availability":{"type":"string","enum":["public","private"],"description":"Type of index availability."},"is_default":{"type":"boolean","description":"Indicates if this is the default index for the data collection."},"speed":{"type":"string","enum":["slow","fast"],"description":"Access speed of the index. Older indices are moved to slower storage."},"state":{"type":"string","enum":["indexing","full"],"description":"Current state of the index. `indexing` indicates that data is still being collected."},"count":{"type":"integer","description":"Count of items in the index."}},"required":["id","name","label","scan_started_at","scan_ended_at","type","availability","count"]},"category":{"description":"Top level fields are grouped to categories for better organization.","type":"string","enum":["addressing","information","protocols","type_of_records","cert_fields","service_fields"]},"field_type":{"description":"Field type determine how different parts of documents are stored and queried.\n","type":"string","enum":["binary","boolean","date","double","float","integer","ip","ip_range","keyword","long","object","scaled_float","short","text","version","wildcard"]},"top_level_field":{"type":"object","title":"Top level field","properties":{"category":{"$ref":"#/components/schemas/category"},"field_type":{"$ref":"#/components/schemas/field_type"}}},"top_level_parent":{"type":"object","title":"Top level field with children","properties":{"category":{"$ref":"#/components/schemas/category"},"children":{"type":"array","description":"The nested fields under the parent field.\n","items":{"type":"object"}}}},"mapping_node":{"description":"A generic mapping node. Leaf nodes expose `field_type`, while parent nodes expose `children`. Top-level fields may additionally include `category`.\n","oneOf":[{"$ref":"#/components/schemas/top_level_field"},{"$ref":"#/components/schemas/top_level_parent"}]},"mapping_response":{"type":"object","description":"A compact recursive representation of the search mapping. Each top-level key is a field name. Leaf fields contain `field_type`. Parent fields contain `children`, where each item is an object with a single nested field name mapped to another generic mapping node.\n","additionalProperties":{"$ref":"#/components/schemas/mapping_node"},"example":{"http":{"category":"protocols","children":[{"headers":{"children":[{"content_type":{"field_type":"keyword"}}]}}]},"ip":{"category":"addressing","field_type":"ip"}}},"node_type":{"type":"string","title":"Node Type","description":"The type of the node(s).\n","enum":["address","as_name","asn","dns_txt","domain","email","favicon","http_tracker","ip","ip-range","jarm","network_name","organization","person","phone","text"],"example":"domain"},"node_value":{"type":"string","description":"A value of the node.\n","example":"example.com"},"X-Count-Id":{"type":"string","description":"The Discovery tool tracks sets of available searches associated with a node or group using this ID.\n","example":"99ec3869b238d440bffc2c6e7b4c8dc3f98cdd9f6b3106d1350cf3c8c0af1837e2942a04780e223b215eb8b663cf5353"},"search_field":{"type":"string","title":"Search Field","description":"The type of search that describes how the search results relate to this object.\n","example":"A records for domain"},"count":{"type":"integer","title":"Count","description":"The number of results for this search type.\n"},"preview":{"type":"array","title":"Preview","description":"Up to five found items as a preview.\n","items":{"oneOf":[{"type":"string"},{"type":"integer"}]}},"search_field_id":{"type":"integer","title":"Search Field ID","description":"The ID of the search type.\n","example":29},"aggregation":{"type":"object","title":"Aggregation","description":"An aggregation representing a search type for a node.\n","properties":{"search_field":{"$ref":"#/components/schemas/search_field"},"count":{"$ref":"#/components/schemas/count"},"preview":{"$ref":"#/components/schemas/preview"},"search_field_id":{"$ref":"#/components/schemas/search_field_id"},"is_too_much_docs":{"type":"boolean","description":"Indicates that the search returns too many documents to add individually, and they should be added as a group."},"node_types":{"type":"object","description":"A breakdown of matching node types returned for this aggregation.\n","additionalProperties":{"type":"integer"}}},"required":["search_field","count","search_field_id"]},"aggregations":{"type":"array","title":"Aggregations","description":"Aggregations are made for data collections. \nEach aggregation contains searches for related entities from this data collection.\n","items":{"$ref":"#/components/schemas/aggregation"}},"node_search_result":{"type":"object","properties":{"node_type":{"$ref":"#/components/schemas/node_type"},"node_value":{"$ref":"#/components/schemas/node_value"},"is_valid":{"type":"boolean","description":"Indicates that the search result should be ignored due to an inappropriate format.\n"}},"required":["node_type","node_value","is_valid"]},"X-Stream-Id":{"type":"string","description":"The unique identifier of a stream used to [track the progress of a search](#tag/Discovery/operation/getGroupRequestStatus).\n","example":"99ec3869b238d440bffc2c6e7b4c8dc3c63309fe08d50c704cba0c91acfedc63"},"stream_status_data":{"type":"object","properties":{"data":{"description":"The search status object contains the following fields:\n","type":"object","properties":{"percentage":{"type":"integer","description":"Percentage of completion","example":33},"message":{"type":"string","description":"Status message","example":"Extracting data"},"status":{"type":"string","description":"Current status of the search","enum":["in progress","done"]}},"required":["percentage","message","status"]}}},"scan_id":{"description":"Unique identifier for the scan.\n","type":"integer","example":123},"scan_name":{"description":"Descriptive label for the scan.\n","type":"string","example":"My Private Scan"},"scan_label":{"description":"A system-defined unique label for the index associated with the scan. Used as an identifier.\n","type":"string","example":"1764230724-u6lrerkpx"},"cidr":{"title":"CIDR","type":"string","pattern":"^((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3})\\/(3[0-2]|[1-2]?\\d)$","description":"A valid CIDR range.","examples":["23.214.224.0/19","194.50.99.237/32"]},"targets":{"description":"A list of targets for the scan. \nValid targets include IP addresses, domain names, and CIDR ranges.\n","type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/ipv4"},{"$ref":"#/components/schemas/domain"},{"$ref":"#/components/schemas/cidr"}]},"example":["example.com","23.215.0.136","23.192.228.80/30"]},"agent_id":{"description":"Identifier of the scanner agent to use for the scan.\n","type":"integer","example":5},"scanner_agent":{"type":"object","description":"Scanner agent that can initiate private scans from a specific geolocation.\n","properties":{"id":{"$ref":"#/components/schemas/agent_id"},"description":{"type":"string","description":"Human-readable description of the scanner agent.","example":"DEMO agent"},"name":{"type":"string","description":"Agent name.","example":"demo-1"},"label":{"type":"string","description":"Agent label.","example":"demo-1"},"location":{"type":"string","description":"Agent geolocation as an ISO 3166-1 alpha-2 country code.","example":"RO"},"ip_address":{"type":"array","description":"Public IP addresses used by the scanner agent.","items":{"$ref":"#/components/schemas/ipv4"},"example":["2.57.122.18","2.57.122.19"]},"is_default":{"type":"boolean","description":"Indicates whether this agent is the default scanner agent for the user."},"queue_eta":{"type":"integer","description":"Estimated queue waiting time for this agent, in seconds.","example":260}},"required":["id","name","label","location","ip_address"]},"private_scan":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/scan_id"},"name":{"$ref":"#/components/schemas/scan_name"},"label":{"$ref":"#/components/schemas/scan_label"},"targets":{"$ref":"#/components/schemas/targets"},"scan_started_at":{"type":["string","null"],"format":"date-time","description":"Timestamp indicating when the scan started."},"scan_ended_at":{"type":["string","null"],"format":"date-time","description":"Timestamp indicating when the scan ended."},"scan_progress":{"type":"array","description":"Provides real-time details about the scan’s progress.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the scan stage."},"state":{"type":"string","description":"The current state of the scan process.","enum":["pending","scheduled","scanning","finalizing","done","failed"]},"description":{"type":["string","null"],"description":"Additional details about the progress."},"timestamp":{"type":"string","format":"date-time","description":"Timestamp of the scan progress update."}},"required":["id","state","timestamp"]}},"created_at":{"type":"string","format":"date-time","description":"Timestamp indicating when the scan was created."},"saved_graph":{"type":["object","null"],"description":"If the scan is associated with a saved attack surface graph, this field contains its metadata.","properties":{"graph_id":{"type":"string","description":"Saved graph identifier."},"graph_name":{"type":"string","description":"Saved graph name."},"graph_version":{"type":"integer","description":"Saved graph version."}},"required":["graph_id","graph_name","graph_version"]},"estimated_time_to_complete":{"type":"integer","description":"Estimated time in seconds to complete the scan."},"queue_position":{"type":["integer","null"],"description":"Position of the scan in the processing queue."},"count":{"type":"integer","description":"Number of items in the index (e.g. number of collected responses)."},"owner":{"type":"object","description":"Information about the owner of the scan.","properties":{"email":{"type":"string","format":"email","description":"Email address of the scan owner."},"first_name":{"type":"string","description":"First name of the scan owner."},"last_name":{"type":"string","description":"Last name of the scan owner."},"teams":{"type":"array","items":{"type":"string"},"description":"List of teams the scan owner belongs to."}},"required":["email","first_name"]},"is_scan_from_team":{"type":"boolean","description":"Indicates whether the scan was initiated by another team member instead of the current user."},"mode":{"type":"string","description":"Scan execution mode."},"state":{"type":"string","description":"Current state of the scan."},"agent":{"anyOf":[{"$ref":"#/components/schemas/scanner_agent"},{"type":"null"}],"description":"Scanner agent used to initiate this scan."}},"required":["id","name","label","targets","created_at","owner","is_scan_from_team","state","mode","agent"],"example":{"id":89,"name":"Test Scan","label":"1764230724-u6lrerkpx","targets":["1.1.1.1"],"created_at":"2025-11-27T08:05:24.518270Z","owner":{"email":"user@netlas.io","first_name":"FName","last_name":"LName","teams":[]},"is_scan_from_team":false,"mode":"top_tcp_ports","state":"done","agent":{"id":5,"description":"DEMO agent","name":"demo-1","label":"demo-1","location":"RO","ip_address":["2.57.122.18","2.57.122.19"],"is_default":true,"queue_eta":260}}},"scan_report":{"type":"object","description":"Scan report object.\nNested `responses` and `cve` structures are intentionally flexible and may vary by protocol or enrichment stage.\n","properties":{"id":{"type":"integer","description":"Report identifier."},"name":{"type":"string","description":"Report name."},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the report was generated."},"scan_id":{"$ref":"#/components/schemas/scan_id"},"scope":{"type":"array","description":"Original scope values used for the scan.","items":{"type":"string"}},"saved_graph":{"type":["object","null"],"description":"Saved attack surface graph metadata associated with the scan report, if any.","additionalProperties":true},"mode":{"type":"string","description":"Scan execution mode."},"agent":{"anyOf":[{"$ref":"#/components/schemas/scanner_agent"},{"type":"null"}],"description":"Scanner agent used to initiate the reported scan."},"responses":{"type":"array","description":"Collected endpoint records. Item structure is dynamic.","items":{"type":"object","additionalProperties":true}},"cve":{"type":"object","description":"Vulnerability matches aggregated from scan results. Structure is dynamic.","additionalProperties":true}},"required":["id","name","created_at","scan_id","scope","saved_graph","mode","agent"],"example":{"id":1001,"name":"Example scan report","created_at":"2026-04-10T12:00:00Z","scan_id":123,"scope":["example.com"],"saved_graph":null,"mode":"top_tcp_ports","agent":{"id":5,"name":"demo-1","label":"demo-1","location":"RO","ip_address":["2.57.122.18","2.57.122.19"]},"responses":[{"uri":"https://example.com:443/","target":"example.com","protocol":"https"},{"uri":"ssh://192.0.2.10:22","target":"192.0.2.10","protocol":"ssh"}],"cve":{"cpe":[{"name":"CVE-2024-0001","severity":"HIGH","uri":"https://example.com:443/"}],"product":[{"name":"CVE-2023-0002","severity":"MEDIUM","uri":"ssh://192.0.2.10:22"}]}}},"shift":{"description":"The number of positions to adjust the scan's priority in the queue.\n\n- A _negative value_ (e.g., `-2`) moves the scan closer to the front, prioritizing it for _earlier execution_.\n- A _positive value_ (e.g., `+3`) moves the scan further back, _delaying its execution_.\n","type":"integer","examples":[-2,1]},"dataset_id":{"type":"integer","description":"A unique identifier for the dataset.","examples":[232,233,269,270,308,316]},"product_id":{"type":"integer","description":"A unique identifier for the product.\n\nDatasets belong to Product objects.\nA product can include one or multiple datasets.\n","examples":[28,80,241,242,279,280]},"Dataset":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/dataset_id"},"product_id":{"$ref":"#/components/schemas/product_id"},"name":{"type":"string","description":"The internal system name of the dataset."},"pretty_name":{"type":"string","description":"Human-readable name of the dataset."},"price":{"type":"string","description":"Price of the dataset in USD."},"added_dt":{"type":"string","format":"date-time","description":"Date and time when the dataset was published."},"samples":{"type":"array","description":"List of dataset samples.","items":{"type":"object"}},"ext":{"type":"array","items":{"type":"string"},"description":"Formats in which the dataset is available."},"description":{"type":"string","description":"Description of the dataset."},"priority":{"type":"integer","description":"Sorting priority of the dataset."},"grouping_args":{"type":"string","description":"_Deprecated field (not used)_.","deprecated":true},"fields":{"type":"array","items":{"type":"string"},"description":"List of fields in the dataset."},"search_query":{"type":"string","description":"The search query linked to this dataset.\nUse this query to find similar data in Netlas Search tools (see `data_type`).\n"},"size":{"type":"object","description":"Size of the dataset in bytes."},"data_type":{"type":"integer","enum":[1,2,4,6,7],"description":"The type of data contained in the dataset:\n- 1: Response data\n- 2: Domain data\n- 4: PTR records\n- 6: IP WHOIS data\n- 7: Domain WHOIS data\n"}},"required":["id","product_id"]},"DatastoreProduct":{"type":"object","properties":{"id":{"type":"integer","description":"A unique identifier for the product."},"description":{"type":"string","description":"Description of the product."},"datasets":{"type":"array","items":{"$ref":"#/components/schemas/Dataset"},"description":"List of datasets included in the product."},"data_type":{"type":"object","description":"Type of product."},"data_category":{"type":"object","description":"Object representing the category of the product."},"count":{"type":"integer","description":"Total count of items in the product."},"size":{"type":"object","description":"Size of the product in bytes."},"name":{"type":"string","description":"System symbolic name of the product."},"pretty_name":{"type":"string","description":"Human-readable (pretty) name of the product."},"fields":{"type":"array","items":{"type":"string"},"description":"List of fields in the product."},"price":{"type":"number","description":"Price of the product in USD."},"priority":{"type":"integer","description":"Sorting priority of the product."},"has_restricted_access":{"type":"boolean","description":"Whether the product is restricted to paid subscribers."},"meta_data":{"type":"object","description":"Additional metadata for the search engines."}},"required":["id","datasets"],"example":{"id":115,"description":"Known domain names with A, MX, NS, CNAME and TXT records.","datasets":[{"id":351,"product_id":115,"name":"fdns","pretty_name":"Forward DNS (fDNS)"}],"name":"fdns","pretty_name":"Forward DNS (fDNS)"}},"DatasetLinks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The internal system name of the dataset link."},"links":{"type":"array","description":"List of links for the dataset.","items":{"type":"object","properties":{"ext":{"type":"string","description":"Format of the dataset link."},"link":{"type":"string","description":"URL of the dataset link."}},"required":["ext","link"]}},"pretty_name":{"type":"string","description":"Human-readable (pretty) name of the dataset link."}},"required":["name","links"]},"example":[{"pretty_name":"Known PTR records (rDNS)","name":"known_ptr_records","links":[{"ext":"json","link":"https://app.netlas.io/storage/known_ptr_records/known_ptr_records.json.zip"}]}]},"user_profile":{"type":"object","properties":{"api_key":{"type":"object","description":"Information about the user's API key.","properties":{"customer_api_key":{"type":"string","description":"The user's unique API key.","example":"eXamPleAPIKey"},"next_time_coins_will_be_updated":{"type":"string","format":"date","description":"The next date when coins will be updated for this API key."}},"required":["customer_api_key","next_time_coins_will_be_updated"]},"email":{"type":"string","format":"email","description":"The user's email address."},"first_name":{"type":"string","description":"The user's first name."},"last_name":{"type":"string","description":"The user's last name."},"account_category":{"type":"string","description":"Data specified during registration.","enum":["company","individual","non-profit"]},"occupation":{"type":"string","description":"Data specified during registration."},"occupation_details":{"type":"string","description":"Data specified during registration."},"is_welcome_tour_passed":{"type":"boolean","description":"Indicates if the user has completed the welcome tour."},"plan":{"type":"object","description":"Information about the user's subscription plan."},"plan_active_until":{"type":["string","null"],"format":"date","description":"The date until the current plan is active."},"next_plan":{"type":"object","description":"Information about the subscription plan that will be activated after the current one expires."},"is_next_plan_paid":{"type":"boolean","description":"Indicates if the next subscription period is paid (used for one-time purchases only)."},"next_plan_paid_period":{"type":"string","description":"The paid period for the next plan."},"referral_code":{"type":"string","description":"The user's referral code."},"bonuses":{"type":"integer","description":"The number of bonus points available to the user."},"notifications":{"type":"array","items":{"type":"integer"},"description":"A list of subscriptions and notification channels."},"teams":{"type":"array","items":{"type":"object"},"description":"A list of teams the user is part of.","example":[{"name":"netlas-team"}]},"is_recurring":{"type":"boolean","description":"Indicates if the subscription is recurring."},"is_authenticated_via_social":{"type":"boolean","description":"Indicates whether the user is authenticated via a third-party service."},"referral_link_usage_amount":{"type":"integer","description":"The number of times the referral link has been used."},"profession":{"type":["string","null"],"description":"_Deprecated field_","deprecated":true},"usage_purpose":{"type":["string","null"],"description":"_Deprecated field_","deprecated":true}}},"user_profile_patch":{"type":"object","properties":{"first_name":{"type":"string","description":"The user's first name."},"last_name":{"type":"string","description":"The user's last name."}},"additionalProperties":false},"user_counters":{"type":"object","title":"User Counters","description":"Usage statistics for the user, including API requests, Netlas Coins, and scan coins.","properties":{"requests_left":{"type":"object","description":"Details about the user's remaining API request quota.","properties":{"remained":{"type":"integer","description":"The number of remaining requests. A value of `-1` indicates unlimited requests.","example":-1},"limit":{"type":"integer","description":"The maximum number of requests allowed. A value of `-1` indicates no limit.","example":-1},"will_be_updated":{"type":["string","null"],"description":"The date when the request limit will be updated. Can be `null` if not applicable.","example":null}},"required":["remained","limit","will_be_updated"]},"coins":{"type":"object","description":"Details about the user's Netlas Coins usage and allocation.","properties":{"total_coins_spent":{"type":"integer","description":"The total number of coins spent by the user.","example":432221783},"left":{"type":"integer","description":"The number of coins left for the user. A value of `-1` indicates unlimited coins.","example":99996653},"plan_coins_amount":{"type":"integer","description":"The total number of coins allocated in the user's plan. A value of `-1` indicates unlimited coins.","example":100000000},"next_time_coins_will_be_updated":{"type":["string","null"],"format":"date","description":"The next date when coins will be updated."}},"required":["total_coins_spent","left","plan_coins_amount","next_time_coins_will_be_updated"]},"scan_coins":{"type":"object","description":"Details about the user's scan coins allocation and usage.","properties":{"plan_scan_coins_amount":{"type":"integer","description":"The total number of scan coins allocated in the user's plan. A value of `-1` indicates unlimited scan coins.","example":327680},"left":{"type":"integer","description":"The number of scan coins left for the user. A value of `-1` indicates unlimited scan coins.","example":327680},"reserved_coins":{"type":"integer","description":"The number of scan coins reserved for ongoing operations.","example":0}},"required":["plan_scan_coins_amount","left","reserved_coins"]}},"required":["requests_left","coins"]}},"responses":{"BAD_REQUEST":{"description":"__Bad Request__: Some required parameters were not passed or were not validated\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ERROR_SCHEMA"},"example":{"detail":"Validation error."}}}},"PAYMENT_REQUIRED":{"description":"__Not Enough Coins__: You are out of your current subscription plan limits\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PAYMENT_REQUIRED_SCHEMA"}}}},"TOO_MANY_REQUESTS":{"description":"__Daily request limit exceeded__ or __Request throttled__. \nAdditional error details are provided in the response body\n","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Daily Request Limit Exceeded","required":["type","detail"],"properties":{"type":{"type":"string","enum":["daily_request_limit_exceeded"]},"title":{"type":"string","enum":["Daily request limit exceeded"]},"detail":{"type":"string","enum":["You can upgrade your plan to increase the daily rate limit or wait until the limit resets."]}}},{"$ref":"#/components/schemas/TOO_MANY_REQUESTS_SCHEMA"}]}}},"headers":{"Retry-After":{"description":"Indicates the number of seconds to wait before retrying the request.\n","schema":{"type":"integer","example":30}}}},"INTERNAL_SERVER_ERROR":{"description":"__Internal Server Error__: Details are included in the response body\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ERROR_SCHEMA"},"example":{"detail":"Internal server error."}}}},"TIMEOUT":{"description":"__Timeout__: The request took too long to process\n","content":{"application/json":{"schema":{"type":"object","title":"Timeout","required":["type","title","detail"],"properties":{"type":{"type":"string","enum":["timeout"]},"title":{"type":"string","enum":["Timeout"]},"detail":{"type":"string","enum":["Unable to process the request at this time. Please try again later."]}}}}}},"ACCESS_DENIED":{"description":"__Access Denied__: You are not allowed to perform this action\nError details are included in the response body.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ACCESS_DENIED_SCHEMA"}}}},"UNAUTHORIZED":{"description":"__Unauthorized__: The request was rejected due to missing or invalid authentication credentials\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UNAUTHORIZED_SCHEMA"}}}},"INDICES_BAD_REQUEST":{"description":"__Bad Request__: Request had invalid authorization credentials (for example, API key not found)\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ERROR_SCHEMA"},"example":{"detail":"Request had invalid authorization credentials: API key not found"}}}},"NOT_FOUND":{"description":"__Not Found__: Requested resource could not be found\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ERROR_SCHEMA"}}}},"SCANNER_NOT_FOUND":{"description":"__Not Found__: The scan with the requested ID was not found\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ERROR_SCHEMA"},"example":{"detail":"The scan with ID 1234 was not found in the user's scans."}}}},"DATASTORE_UNAUTHORIZED":{"description":"__Unauthorized__: The request was rejected due to missing or invalid authentication credentials\n","content":{"application/json":{"schema":{"type":"object","title":"Authorization required","required":["type","title","detail"],"properties":{"type":{"type":"string","enum":["authorization_required"]},"title":{"type":"string","enum":["Authorization required"]},"detail":{"type":"string","enum":["You have to be signed in to perform this operation"]}}}}}},"DATASTORE_PAYMENT_REQUIRED":{"description":"__Payment Required__: This product requires payment on your subscription plan\n","content":{"application/json":{"schema":{"type":"object","title":"Payment Required","required":["type","title","detail"],"properties":{"type":{"type":"string","enum":["product_not_available_for_free"]},"title":{"type":"string","enum":["Payment Required"]},"detail":{"type":"string","enum":["This product requires payment on your subscription plan."]}}}}}},"USERS_BAD_REQUEST":{"description":"__Bad Request__: Request had invalid authorization credentials or malformed input\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ERROR_SCHEMA"},"examples":{"invalidApiKey":{"summary":"Invalid API key","value":{"detail":"Request had invalid authorization credentials: API key not found"}},"invalidJson":{"summary":"Malformed JSON body","value":{"detail":"JSON parse error - Expecting property name enclosed in double quotes: line 1 column 2 (char 1)"}}}}}},"USERS_ACCESS_DENIED":{"description":"__Access Denied__: Changing this field is not allowed\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ACCESS_DENIED_SCHEMA"},"example":{"type":"access_denied","title":"Access Denied","detail":"Changing this field is not allowed."}}}}}},"security":[{"BearerAuth":[]}],"tags":[{"name":"Host Info","description":"Retrieves a summary of Netlas data for a specific IP address or domain name.\n\n The Host Info endpoint supports queries by IP or domain only, but returns aggregated data from all Netlas data collections in a single response.\n\n The same data available in the Netlas web interface via the IP/Domain Info tool.\n"},{"name":"Responses","description":"Access continuously updated internet scan data collected by Netlas.\n\n The same data available in the Netlas web interface via the Responses Search tool.\n"},{"name":"Domains","description":"Information about domain names, their corresponding IP addresses, and other types of DNS records.\n\n The same data available in the Netlas web interface via the DNS Search tool.\n"},{"name":"IP WHOIS","description":"Provides information on IP address ownership, network provider details, contact information, and other WHOIS data.\n\n The same data available in the Netlas web interface via the IP WHOIS Search tool.\n"},{"name":"Domain WHOIS","description":"Information on domain ownership, registrar details, contact information, registration dates, expiration dates, and other WHOIS data.\n\n The same data available in the Netlas web interface via the Domain WHOIS Search tool.\n"},{"name":"Certificates","description":"A collection of x.509 certificates gathered from various sources.\n\n The same data available in the Netlas web interface via the Certificates Search tool.\n"},{"name":"Indices","description":"Netlas organizes its data into indices. Each search tool has a dedicated set of indices with data collected on specific dates.\n\nResponses search tool also provides access to private indices:\n- __Public indices__: regular Netlas indices available to all Netlas users.\n- __Private indices__: indices produced by using Private Scanner by you or shared with you by your teammates.\n"},{"name":"Mapping","description":"Netlas stores collected data as JSON documents, organized into several data collections, such as Responses and Domains.\nEach data collection has its own mapping, which defines its document structure. \n\nThis group of methods provides access to the mapping of each data collection.\n"},{"name":"Discovery","description":"\nThe Attack Surface Discovery tool helps explore and analyze relationships between internet entities such as IP addresses, \ndomain names, networks, WHOIS records, and more.\n\nThis group of endpoints is used by the Discovery tool in the Netlas web app.\n"},{"name":"Scanner","description":"The Netlas Private Scanner performs non-intrusive scans of internet-connected assets.\n\nThis group of endpoints is used by the Private Scanner tool in the Netlas web app.\n"},{"name":"Datastore","description":"The Netlas Datastore API provides access to a wide range of network-related datasets.\n\nUse these endpoints to access the Netlas Datastore.\n"},{"name":"Users","description":"User profile data and settings.\n"}],"paths":{"/api/host/{host}/":{"get":{"tags":["Host Info"],"operationId":"host","security":[],"summary":"Host Summary","description":"Retrieve the latest available data for `{host}`.\n","parameters":[{"name":"host","in":"path","required":true,"description":"The IP address or domain name for which data should be retrieved.\n","schema":{"oneOf":[{"$ref":"#/components/schemas/ipv4"},{"$ref":"#/components/schemas/domain"}]}},{"name":"fields","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/fields"}},{"name":"source_type","in":"query","schema":{"$ref":"#/components/schemas/source_type"}},{"name":"public_indices_only","in":"query","schema":{"$ref":"#/components/schemas/public_indices_only"}}],"responses":{"200":{"description":"__Host Summary__","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/HostResponseByIP"},{"$ref":"#/components/schemas/HostResponseByDomain"}]}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"# IP query example\ncurl -s -X GET \\\n \"https://app.netlas.io/api/host/23.215.0.136/\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\"\n\n# Domain query example\ncurl -s -X GET \\\n \"https://app.netlas.io/api/host/example.com/\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\"\n\n# Filtering output\ncurl -s -X GET \\\n\"https://app.netlas.io/api/host/google.com/\" \\\n -G \\\n --data-urlencode 'fields=whois.registrant.organization' \\\n --data-urlencode 'source_type=include' \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"# IP query example\nnetlas host \"23.215.0.136\" -f json\n\n# Domain query example\nnetlas host \"example.com\" -f json\n\n# Filtering output\nnetlas host \"google.com\" \\\n --format json \\\n --include \"whois.registrant.organization\""},{"lang":"Python","source":"import netlas\nimport json\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\n# IP query example\nip_info = netlas_connection.host(host=\"23.215.0.136\")\nprint(json.dumps(ip_info))\n\n# Domain query example\ndomain_info = netlas_connection.host(host=\"example.com\")\nprint(json.dumps(domain_info))\n\n# Filtering output\ndomain_info = netlas_connection.host(\n host=\"google.com\", \n fields=\"whois.registrant.organization\"\n)\nprint(json.dumps(domain_info))\n"}],"x-netlas-cli":{"supported":true,"tool":"host","template":"netlas host {host} {field_selection} --format json","args":{"host":{"source":"path.host","kind":"positional","position":0,"required":true},"fields":{"source":"query.fields","kind":"option","join":",","selector":"source_type","flags":{"include":"--include","exclude":"--exclude"}},"source_type":{"source":"query.source_type","kind":"selector","default":"include"},"public_indices_only":{"source":"query.public_indices_only","unsupported":true,"reason":"Current Netlas CLI host command does not expose public_indices_only."},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/host/":{"get":{"tags":["Host Info"],"operationId":"hostSelf","security":[],"summary":"Caller’s Host Summary","description":"Retrieves the latest available data for the IP address of the client making the request.\n\nUse this method to obtain information about your own IP address.\n","parameters":[{"name":"fields","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/fields"}},{"name":"source_type","in":"query","schema":{"$ref":"#/components/schemas/source_type"}},{"name":"public_indices_only","in":"query","required":false,"schema":{"$ref":"#/components/schemas/public_indices_only"}}],"responses":{"200":{"description":"__Host Summary__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostResponseByIP"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/host/\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas host -f json"},{"lang":"Python","source":"import netlas\nimport json\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nip_info = netlas_connection.host(host=None)\nprint(json.dumps(ip_info))\n"}],"x-netlas-cli":{"supported":true,"tool":"host","template":"netlas host {field_selection} --format json","args":{"fields":{"source":"query.fields","kind":"option","join":",","selector":"source_type","flags":{"include":"--include","exclude":"--exclude"}},"source_type":{"source":"query.source_type","kind":"selector","default":"include"},"public_indices_only":{"source":"query.public_indices_only","unsupported":true,"reason":"Current Netlas CLI host command does not expose public_indices_only."},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/responses/":{"get":{"tags":["Responses"],"operationId":"responsesSearch","security":[],"summary":"Responses Search","description":"Searches for `q` in the selected `indices` and returns up to 20 search results, starting from the `start+1` document.\n \n❗️ This method allows retrieving only the first 10,000 search results.\n\nUse it when the expected number of results is relatively low or to craft and refine a query.\nUse the __Download__ endpoint to fetch results without pagination or quantity limitations.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"examples":{"hostSearchExample":{"value":"host:example.com","description":"responses for a specific host"},"ipRangeSearchExample":{"value":"ip:[1.1.1.1 TO 1.1.1.255]","description":"responses for a specific IP range"},"protocolAndCountySearchExample":{"value":"protocol:ftp AND geo.country:VA","description":"specific protocol and country"}}},{"name":"start","in":"query","required":false,"schema":{"$ref":"#/components/schemas/start"}},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices"},"description":"A list of [indices](#tag/Indices) where the search will be performed.\n\nℹ️ Unlike other search tools, Responses search does not have a default index. \nIf `indices` is not specified, the search is conducted using the latest publicly available internet scan data, \nwhich is updated in real time.\n","examples":{"DefaultIndiceSearch":{"value":[],"description":"Search in the latest data available"},"SearchInFewIndices":{"value":["2025-09-24","2025-09-02"],"description":"Search in specific indices"},"SearchInPrivateIndices":{"value":["1764230724-u6lrerkpx"],"description":"Search in private index"}}},{"name":"fields","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/fields"},"example":["uri"]},{"name":"source_type","in":"query","required":false,"schema":{"$ref":"#/components/schemas/source_type"}}],"responses":{"200":{"description":"__Search Results__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesSearch"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/responses/\" \\\n -G \\\n --data-urlencode \"q=host:example.com\" \\\n --data-urlencode \"fields=ip,uri\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas search \"host:example.com\" \\\n --include ip,uri \\\n --format json"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"host:example.com\"\nfields = \"ip,uri\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nsearch_results = netlas_connection.search(query, fields=fields)\nprint(json.dumps(search_results))"}],"x-netlas-cli":{"tool":"search","template":"netlas search \"{q}\" {field_selection} --format json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"fields":{"source":"query.fields","kind":"option","join":",","selector":"source_type","flags":{"include":"--include","exclude":"--exclude"}},"source_type":{"source":"query.source_type","kind":"selector","default":"include"},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"start":{"source":"query.start","unsupported":true,"reason":"Use CLI --page instead; the API start offset has no direct CLI equivalent."},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/responses_count/":{"get":{"tags":["Responses"],"operationId":"responsesCount","security":[],"summary":"Responses Count","description":"Counts the number of documents matching the search query `q` in the selected `indices`.\n\n- If there are fewer than 1,000 results, the method returns the exact count.\n- If there are more than 1,000 results, the count is estimated with an error margin not exceeding 3%.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"example":"ip:\"23.192.0.0/11\""},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices"},"description":"A list of [indices](#tag/Indices) where the search will be performed.\n\nℹ️ Unlike other search tools, Responses search does not have a default index. \nIf `indices` is not specified, the search is conducted using the latest publicly available internet scan data, \nwhich is updated in real time.\n","examples":{"DefaultIndiceSearch":{"value":[],"description":"Search in the latest data available"},"SearchInFewIndices":{"value":["2025-09-24","2025-09-02"],"description":"Search in specific indices"},"SearchInPrivateIndices":{"value":["1764230724-u6lrerkpx"],"description":"Search in private index"}}}],"responses":{"200":{"description":"__Count__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Count"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/responses_count/\" \\\n -G \\\n --data-urlencode 'q=ip:\"23.192.0.0/11\"' \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas count 'ip:\"23.192.0.0/11\"' -f json"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"ip:\\\"23.192.0.0/11\\\"\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\ncount_results = netlas_connection.count(query)\nprint(json.dumps(count_results))"}],"x-netlas-cli":{"tool":"count","template":"netlas count \"{q}\" -d response -f json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"datatype":{"kind":"fixed","flag":"--datatype","value":"response"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/responses/download/":{"post":{"tags":["Responses"],"operationId":"responsesDownload","summary":"Responses Download","description":"Retrieves `size` search results matching the query `q` in the selected `indices`.\n\nThe Netlas SDK and CLI tool additionally include a `download_all()` method and an `--all` key that allow you to query all available results.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadPayload"},"example":{"q":"ip:\"23.192.0.0/11\"","size":100,"fields":["uri","host_type","port","prot4","prot7","protocol"],"source_type":"include","indices":["2025-09-24"]}}}},"responses":{"200":{"description":"__Search Results__","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ResponsesDownloadJSON"},{"$ref":"#/components/schemas/DownloadCSV"}]},"example":[{"data":{"path":"/ClientPortal/Login.aspx","protocol":"https","prot4":"tcp","port":443,"ip":"23.218.66.148","host":"ww4.autotask.net","host_type":"domain","prot7":"http","ptr":["a23-218-66-148.deploy.static.akamaitechnologies.com"]}},{"data":{"path":"/taxfreedom/","protocol":"http","prot4":"tcp","port":80,"ip":"23.218.68.10","host":"turbotax.intuit.com","host_type":"domain","prot7":"http","ptr":["a23-218-68-10.deploy.static.akamaitechnologies.com"]}},{"data":{"path":"/taxfreedom/","protocol":"https","prot4":"tcp","port":443,"ip":"23.218.68.10","host":"turbotax.intuit.com","host_type":"domain","prot7":"http","ptr":["a23-218-68-10.deploy.static.akamaitechnologies.com"]}},{"data":{"path":"/saml/login/8141776/87e9","protocol":"https","prot4":"tcp","port":443,"ip":"23.200.189.212","host":"lastpass.com","host_type":"domain","prot7":"http","ptr":["a23-200-189-212.deploy.static.akamaitechnologies.com"]}},{"data":{"path":"/61b1ba49b79d/intresseanmlan-mi-ntverket-2018-ett-arbetsseminarium-workshop-med-dr-stephen/","protocol":"https","prot4":"tcp","port":443,"ip":"23.209.18.242","host":"mailchi.mp","host_type":"domain","prot7":"http","ptr":["a23-209-18-242.deploy.static.akamaitechnologies.com"]}}]}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X POST \\\n \"https://app.netlas.io/api/responses/download/\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -d '{\n \"q\": \"ip:\\\"23.192.0.0/11\\\"\",\n \"fields\": [\"domain\", \"host\", \"host_type\", \"ip\", \"path\", \"port\", \"prot4\", \"prot7\", \"protocol\", \"ptr\"],\n \"size\": 100,\n \"source_type\": \"include\"\n }'\n "},{"lang":"Netlas CLI","source":"netlas download \"ip:\\\"23.192.0.0/11\\\"\" \\\n --include domain,host,host_type,ip,path,port,prot4,prot7,protocol,ptr \\\n --count 100 # --all to download all results (no need to specify --count)\n \n"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"ip:\\\"23.192.0.0/11\\\"\"\nfields = \"domain,host,host_type,ip,path,port,prot4,prot7,protocol,ptr\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n \nfor r in netlas_connection.download(\n query, fields, size=100\n # use Netlas.download_all() to download all results\n # (no need to specify size parameter)\n ):\n response = json.loads(r.decode(\"utf-8\"))\n print(json.dumps(response))"}],"x-netlas-cli":{"tool":"download","template":"netlas download \"{q}\" {field_selection} --count {size} --datatype response","args":{"q":{"source":"body.q","kind":"positional","position":0,"required":true},"fields":{"source":"body.fields","kind":"option","join":",","selector":"source_type","flags":{"include":"--include","exclude":"--exclude"}},"source_type":{"source":"body.source_type","kind":"selector","default":"include"},"size":{"source":"body.size","kind":"option","flag":"--count"},"indices":{"source":"body.indices","kind":"option","flag":"--indices","join":","},"datatype":{"kind":"fixed","flag":"--datatype","value":"response"}}}}},"/api/responses_facet/":{"get":{"tags":["Responses"],"operationId":"responsesFacet","security":[],"summary":"Responses Facet Search","description":"Searches for `q` in the selected `indices` and groups results by the `facets` field.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"example":"ip:\"23.192.0.0/11\""},{"name":"facets","in":"query","required":true,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/facets"},"example":["protocol"]},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices"},"description":"A list of [indices](#tag/Indices) where the search will be performed.\n\nℹ️ Unlike other search tools, Responses search does not have a default index. \nIf `indices` is not specified, the search is conducted using the latest publicly available internet scan data, \nwhich is updated in real time.\n","examples":{"DefaultIndiceSearch":{"value":[],"description":"Search in the latest data available"},"SearchInFewIndices":{"value":["2025-09-24","2025-09-02"],"description":"Search in specific indices"},"SearchInPrivateIndices":{"value":["1764230724-u6lrerkpx"],"description":"Search in private index"}}},{"name":"size","in":"query","required":false,"schema":{"$ref":"#/components/schemas/facet_search_size"}}],"responses":{"200":{"description":"__Facet Search Results__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetSearchResults"},"example":{"aggregations":[{"key":["http"],"doc_count":1675766},{"key":["https"],"doc_count":1161498},{"key":["dns_tcp"],"doc_count":15834},{"key":["dns"],"doc_count":14602},{"key":["ssh"],"doc_count":973}]}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/responses_facet/\" \\\n -G \\\n --data-urlencode 'q=ip:\"23.192.0.0/11\"' \\\n --data-urlencode 'facets=protocol' \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas facet 'ip:\"23.192.0.0/11\"' \\\n --group_fields protocol \\\n --format json"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"ip:\\\"23.192.0.0/11\\\"\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nresults = netlas_connection.stat(\n query,\n facets=\"protocol\",\n index_type=\"responses\",\n)\nprint(json.dumps(results))\n"}],"x-netlas-cli":{"tool":"facet","template":"netlas facet \"{q}\" --group_fields {facets} --index_type response --format json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"facets":{"source":"query.facets","kind":"option","flag":"--group_fields","join":",","required":true},"size":{"source":"query.size","kind":"option","flag":"--size"},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"index_type":{"kind":"fixed","flag":"--index_type","value":"response"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/domains/":{"get":{"tags":["Domains"],"operationId":"domainsSearch","security":[],"summary":"Domains Search","description":"Searches for `q` in the selected `indices` and returns up to 20 search results, starting from the `start+1` document.\n \n❗️ This method allows retrieving only the first 10,000 search results.\n\nUse it when the expected number of results is relatively low or to craft and refine a query.\nUse the __Download__ endpoint to fetch results without pagination or quantity limitations.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"examples":{"domainSearchExample":{"value":"domain:*.example.com a:*","description":"subdomains of example.com with any A record"},"regexSearchExample":{"value":"domain:/(.*\\.)?paypal\\.[a-z0-9-]*/","description":"domains and subdomains named \"paypal\" (regex)"},"nsSearchExample":{"value":"ns:*.cloudflare.com","description":"domains using Cloudflare name servers"}}},{"name":"start","in":"query","schema":{"$ref":"#/components/schemas/start"}},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices"}},{"name":"fields","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/fields","examples":["*","domain,a"]}},{"name":"source_type","in":"query","schema":{"$ref":"#/components/schemas/source_type"}}],"responses":{"200":{"description":"__Search Results__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainsSearch"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/domains/\" \\\n -G \\\n --data-urlencode \"q=domain:example.com\" \\\n --data-urlencode \"fields=a,aaaa,ns,mx,txt\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas search \"domain:example.com\" \\\n --datatype domain \\\n --include a,aaaa,ns,mx,txt \\\n --format json"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"domain:example.com\"\nfields = \"a,aaaa,ns,mx,txt\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nsearch_results = netlas_connection.search(\n query, datatype=\"domain\", fields=fields\n )\nprint(json.dumps(search_results))\n"}],"x-netlas-cli":{"supported":true,"tool":"search","template":"netlas search \"{q}\" --datatype domain {field_selection} --format json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"fields":{"source":"query.fields","kind":"option","join":",","selector":"source_type","flags":{"include":"--include","exclude":"--exclude"}},"source_type":{"source":"query.source_type","kind":"selector","default":"include"},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"start":{"source":"query.start","unsupported":true,"reason":"Use CLI --page instead; the API start offset has no direct CLI equivalent."},"datatype":{"kind":"fixed","flag":"--datatype","value":"domain"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/domains_count/":{"get":{"tags":["Domains"],"operationId":"domainsCount","security":[],"summary":"Domains Count","description":"Counts the number of documents matching the search query `q` in the selected `indices`.\n\n- If there are fewer than 1,000 results, the method returns the exact count.\n- If there are more than 1,000 results, the count is estimated with an error margin not exceeding 3%.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"example":"domain:*.example.com a:*"},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices"}}],"responses":{"200":{"description":"__Count__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Count"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/domains_count/\" \\\n -G \\\n --data-urlencode \"q=domain:*.example.com a:*\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas count \"domain:*.example.com a:*\" \\\n --datatype domain \\\n --format json"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"domain:*.example.com a:*\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\ncount_results = netlas_connection.count(\n query, datatype=\"domain\"\n )\nprint(json.dumps(count_results))"}],"x-netlas-cli":{"supported":true,"tool":"count","template":"netlas count \"{q}\" --datatype domain --format json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"datatype":{"kind":"fixed","flag":"--datatype","value":"domain"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/domains/download/":{"post":{"tags":["Domains"],"operationId":"domainsDownload","summary":"Domains Download","description":"Retrieves `size` search results matching the query `q` in the selected `indices`.\n\nThe Netlas SDK and CLI tool additionally include a `download_all()` method and an `--all` key that allow you to query all available results.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadPayload"},"example":{"q":"domain:*.example.com a:*","size":100,"fields":["a","domain"],"source_type":"include"}}}},"responses":{"200":{"description":"__Search Results__","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/DomainsDownloadJSON"},{"$ref":"#/components/schemas/DownloadCSV"}]},"example":[{"data":{"a":["83.235.76.17"],"domain":"idn3241.example.com"}},{"data":{"a":["143.244.220.150"],"domain":"skadowskyu.example.com"}},{"data":{"a":["212.109.215.174","212.109.215.175"],"domain":"server9.example.com"}},{"data":{"a":["83.235.76.17"],"domain":"del1.example.com"}},{"data":{"a":["212.109.215.174","212.109.215.175"],"domain":"n.parfionov2017.example.com"}}]}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X POST \\\n \"https://app.netlas.io/api/domains/download/\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -d '{\n \"q\": \"domain:*.example.com a:*\",\n \"fields\": [\"domain\", \"a\"],\n \"size\": 100,\n \"source_type\": \"include\"\n }'\n "},{"lang":"Netlas CLI","source":"netlas download \"domain:*.example.com a:*\" \\\n --datatype domain \\\n --include domain,a \\\n --count 100 # --all to download all results (no need to specify --count)\n \n"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"domain:*.example.com a:*\"\nfields = \"domain,a\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n \nfor r in netlas_connection.download(\n query, fields, datatype=\"domain\" ,size=100\n # use Netlas.download_all() to download all results\n # (no need to specify size parameter)\n ):\n response = json.loads(r.decode(\"utf-8\"))\n print(json.dumps(response))"}],"x-netlas-cli":{"supported":true,"tool":"download","template":"netlas download \"{q}\" --datatype domain {field_selection} --count {size} --format json","args":{"q":{"source":"body.q","kind":"positional","position":0,"required":true},"fields":{"source":"body.fields","kind":"option","join":",","selector":"source_type","flags":{"include":"--include","exclude":"--exclude"}},"source_type":{"source":"body.source_type","kind":"selector","default":"include"},"size":{"source":"body.size","kind":"option","flag":"--count"},"indices":{"source":"body.indices","kind":"option","flag":"--indices","join":","},"datatype":{"kind":"fixed","flag":"--datatype","value":"domain"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/domains_facet/":{"get":{"tags":["Domains"],"operationId":"domainsFacet","security":[],"summary":"Domains Facet Search","description":"Searches for `q` in the selected `indices` and groups results by the `facets` field.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"example":"level:2"},{"name":"facets","in":"query","required":true,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/facets"},"example":["zone"]},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices"}},{"name":"size","in":"query","schema":{"$ref":"#/components/schemas/facet_search_size"}}],"responses":{"200":{"description":"__Facet Search Results__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetSearchResults"},"example":{"aggregations":[{"key":["com"],"doc_count":382078579},{"key":["net"],"doc_count":21890693},{"key":["org"],"doc_count":17769023},{"key":["top"],"doc_count":15855678},{"key":["tk"],"doc_count":12662280}]}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/domains_facet/\" \\\n -G \\\n --data-urlencode 'q=level:2' \\\n --data-urlencode 'facets=zone' \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas facet \"domain:*.example.com a:*\" \\\n --group_fields a \\\n --index_type domain \\\n --format json\n"},{"lang":"Python","source":"import json\nimport netlas\n\nquery = \"domain:*.example.com a:*\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nresults = netlas_connection.stat(query, facets=\"a\", index_type=\"domain\")\nprint(json.dumps(results))\n"}],"x-netlas-cli":{"supported":true,"tool":"facet","template":"netlas facet \"{q}\" --group_fields {facets} --index_type domain --format json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"facets":{"source":"query.facets","kind":"option","flag":"--group_fields","join":",","required":true},"size":{"source":"query.size","kind":"option","flag":"--size"},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"index_type":{"kind":"fixed","flag":"--index_type","value":"domain"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/whois_ip/":{"get":{"tags":["IP WHOIS"],"operationId":"ipWhoisSearch","security":[],"summary":"IP WHOIS Search","description":"Searches for `q` in the selected `indices` and returns up to 20 search results, starting from the `start+1` document.\n \n❗️ This method allows retrieving only the first 10,000 search results.\n\nUse it when the expected number of results is relatively low or to craft and refine a query.\nUse the __Download__ endpoint to fetch results without pagination or quantity limitations.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"examples":{"ipSearchExample":{"value":"ip:23.215.0.136","description":"search for a specific IP address"},"cidrSearchExample":{"value":"net.cidr:1.1.1.0 net.net_size:255","description":"search for a specific CIDR range"},"organizationSearchExample":{"value":"net.organization:Mandiant","description":"networks related to a specific organization"}}},{"name":"start","in":"query","schema":{"$ref":"#/components/schemas/start"}},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices"}},{"name":"fields","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/fields"},"example":["organization","net.country","net.range"]},{"name":"source_type","in":"query","schema":{"$ref":"#/components/schemas/source_type"}}],"responses":{"200":{"description":"__Search Results__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IpWhoisSearch"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/whois_ip/\" \\\n -G \\\n --data-urlencode \"q=ip:212.77.12.64\" \\\n --data-urlencode \"fields=net,asn\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\"\n"},{"lang":"Netlas CLI","source":"netlas search \"ip:23.215.0.136\" \\\n --datatype whois-ip \\\n --include net,asn \\\n --format json"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"ip:23.215.0.136\"\nfields = \"net,asn\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nsearch_results = netlas_connection.search(\n query, datatype=\"whois-ip\", fields=fields\n )\nprint(json.dumps(search_results))\n"}],"x-netlas-cli":{"supported":true,"tool":"search","template":"netlas search \"{q}\" --datatype whois-ip {field_selection} --format json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"fields":{"source":"query.fields","kind":"option","join":",","selector":"source_type","flags":{"include":"--include","exclude":"--exclude"}},"source_type":{"source":"query.source_type","kind":"selector","default":"include"},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"start":{"source":"query.start","unsupported":true,"reason":"Use CLI --page instead; the API start offset has no direct CLI equivalent."},"datatype":{"kind":"fixed","flag":"--datatype","value":"whois-ip"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/whois_ip_count/":{"get":{"tags":["IP WHOIS"],"operationId":"ipWhoisCount","security":[],"summary":"IP WHOIS Count","description":"Counts the number of documents matching the search query `q` in the selected `indices`.\n\n- If there are fewer than 1,000 results, the method returns the exact count.\n- If there are more than 1,000 results, the count is estimated with an error margin not exceeding 3%.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"example":"net.country:VA"},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices"}}],"responses":{"200":{"description":"__Count__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Count"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/whois_ip_count/\" \\\n -G \\\n --data-urlencode \"q=net.country:VA\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas count \"net.country:VA\" \\\n --datatype whois-ip \\\n --format json"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"net.country:VA\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\ncount_results = netlas_connection.count(\n query, datatype=\"whois-ip\"\n )\nprint(json.dumps(count_results))"}],"x-netlas-cli":{"supported":true,"tool":"count","template":"netlas count \"{q}\" --datatype whois-ip --format json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"datatype":{"kind":"fixed","flag":"--datatype","value":"whois-ip"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/whois_ip/download/":{"post":{"tags":["IP WHOIS"],"operationId":"ipWhoisDownload","summary":"IP WHOIS Download","description":"Retrieves `size` search results matching the query `q` in the selected `indices`.\n\nThe Netlas SDK and CLI tool additionally include a `download_all()` method and an `--all` key that allow you to query all available results.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadPayload"},"example":{"q":"net.country:VA","size":100,"fields":["abuse","asn","net"],"source_type":"include"}}}},"responses":{"200":{"description":"__Search Results__","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/IpWhoisDownloadJSON"},{"$ref":"#/components/schemas/DownloadCSV"}]},"example":[{"data":{"abuse":"abuse@securebit.ch","net":{"country":"VA","address":"Securebit AG\nIndustriestrasse 3\n6345 Neuheim\nSwitzerland","created":"2020-02-02T02:04:48Z","name":"VA-SECUREBIT-20200202","start_ip":"194.50.99.237","range":"194.50.99.237 - 194.50.99.237","description":"Securebit Network Holy See (Vatican City State)","cidr":["194.50.99.237/32"],"handle":"SBAC-RIPE","net_size":0,"updated":"2020-02-02T02:04:48Z","end_ip":"194.50.99.237"},"asn":{"number":["34800"],"registry":"ripencc","country":"CH","name":"SBAG Securebit Autonomous System","cidr":"194.50.99.0/24","updated":"2019-11-21"}}},{"data":{"abuse":"abuse@urbe.it","net":{"country":"VA","address":"Via della Scrofa, 70\n00186\nRoma\nITALY","created":"2002-04-11T09:28:47Z","range":"193.43.128.0 - 193.43.131.255","handle":"MC30359-RIPE","organization":"URBE: Unione Romana Biblioteche Ecclesiastiche","name":"URBE-NET","start_ip":"193.43.128.0","cidr":["193.43.128.0/22"],"net_size":1023,"updated":"2016-05-04T08:55:35Z","end_ip":"193.43.131.255","remarks":"Pontifical University of the Holy Cross\nPontificia Universita della Santa Croce\nRome","contacts":{"persons":["Massimo Cuccu","Salvatore Toribio"],"phones":["+390683396190","+39 06681641","+39 06 681641"]}},"asn":{"number":["8978"],"registry":"ripencc","country":"IT","name":"ASN-HOLYSEE Holy See Secretariat of State Department of Telecommunications","cidr":"193.43.128.0/22","updated":"1995-04-04"}}},{"data":{"abuse":"abuse@vatlib.it","net":{"country":"VA","address":"Cortile del Belvedere SNC\n00120\nVatican City\nHOLY SEE (VATICAN CITY STATE)","created":"1970-01-01T00:00:00Z","range":"193.43.102.0 - 193.43.103.255","handle":"MM56992-RIPE","organization":"Biblioteca Apostolica Vaticana","name":"VATICAN-LIBRARY-NET","start_ip":"193.43.102.0","cidr":["193.43.102.0/23"],"net_size":511,"updated":"2022-10-04T12:46:18Z","end_ip":"193.43.103.255","remarks":"Multiple Interconnected Servers and LANs","contacts":{"persons":["Manlio Miceli"],"phones":["+390669879478"]}},"asn":{"number":["61160"],"registry":"ripencc","country":"VA","name":"ASN-VATLIB","cidr":"193.43.102.0/23","updated":"1995-02-06"}}},{"data":{"abuse":"abuse@spc.va","net":{"country":"VA","address":"5, Via della Conciliazione\n00120\nVatican City\nHOLY SEE (VATICAN CITY STATE)","created":"2024-08-22T07:59:09Z","name":"DPC-Guest-Users","start_ip":"185.152.69.252","range":"185.152.69.252 - 185.152.69.255","cidr":["185.152.69.252/30"],"handle":"SC18373-RIPE","net_size":3,"updated":"2024-08-22T07:59:09Z","end_ip":"185.152.69.255","contacts":{"persons":["net admin"],"phones":["+393346900701"]}},"asn":{"number":["202865"],"registry":"ripencc","country":"VA","name":"SPC","cidr":"185.152.69.0/24","updated":"2016-05-17"}}},{"data":{"abuse":"abuse@spc.va","net":{"country":"VA","address":"Casina Pio IV, 00120 Citt del Vaticano","created":"2024-08-22T07:58:09Z","name":"PAS-Users","start_ip":"185.152.69.250","range":"185.152.69.250 - 185.152.69.251","cidr":["185.152.69.250/31"],"handle":"LR9247-RIPE","net_size":1,"updated":"2024-08-22T07:58:09Z","end_ip":"185.152.69.251","contacts":{"persons":["Lorenzo Rumori","Nicola Riccardi"],"phones":["+39 0669883451"]}},"asn":{"number":["202865"],"registry":"ripencc","country":"VA","name":"SPC","cidr":"185.152.69.0/24","updated":"2016-05-17"}}}]}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X POST \\\n \"https://app.netlas.io/api/whois_ip/download/\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -d '{\n \"q\": \"net.country:VA\",\n \"fields\": [\"abuse\", \"asn\", \"net\"],\n \"size\": 100,\n \"source_type\": \"include\"\n }'\n "},{"lang":"Netlas CLI","source":"netlas download \"net.country:VA\" \\\n --datatype whois-ip \\\n --include abuse,asn,net \\\n --count 100 # --all to download all results (no need to specify --count)\n "},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"net.country:VA\"\nfields = \"abuse,asn,net\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n \nfor r in netlas_connection.download(\n query, fields, datatype=\"whois-ip\" ,size=100\n # use Netlas.download_all() to download all results\n # (no need to specify size parameter)\n ):\n response = json.loads(r.decode(\"utf-8\"))\n print(json.dumps(response))"}],"x-netlas-cli":{"supported":true,"tool":"download","template":"netlas download \"{q}\" --datatype whois-ip {field_selection} --count {size} --format json","args":{"q":{"source":"body.q","kind":"positional","position":0,"required":true},"fields":{"source":"body.fields","kind":"option","join":",","selector":"source_type","flags":{"include":"--include","exclude":"--exclude"}},"source_type":{"source":"body.source_type","kind":"selector","default":"include"},"size":{"source":"body.size","kind":"option","flag":"--count"},"indices":{"source":"body.indices","kind":"option","flag":"--indices","join":","},"datatype":{"kind":"fixed","flag":"--datatype","value":"whois-ip"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/whois_ip_facet/":{"get":{"tags":["IP WHOIS"],"operationId":"ipWhoisFacet","security":[],"summary":"IP WHOIS Facet Search","description":"Searches for `q` in the selected `indices` and groups results by the `facets` field.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"example":"*"},{"name":"facets","in":"query","required":true,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/facets"},"example":["net.country"]},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices"}},{"name":"size","in":"query","schema":{"$ref":"#/components/schemas/facet_search_size"}}],"responses":{"200":{"description":"__Facet Search Results__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetSearchResults"},"example":{"aggregations":[{"key":["US"],"doc_count":3811776},{"key":["IT"],"doc_count":762034},{"key":["GB"],"doc_count":732744},{"key":["JP"],"doc_count":614086},{"key":["FR"],"doc_count":574712}]}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/whois_ip_facet/\" \\\n -G \\\n --data-urlencode 'q=*' \\\n --data-urlencode 'facets=net.country' \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas facet \"net.country:VA\" \\\n --group_fields net.country \\\n --index_type whois-ip \\\n --format json\n"},{"lang":"Python","source":"import json\nimport netlas\n\nquery = \"net.country:VA\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nresults = netlas_connection.stat(query, facets=\"net.country\", index_type=\"whois-ip\")\nprint(json.dumps(results))\n"}],"x-netlas-cli":{"supported":true,"tool":"facet","template":"netlas facet \"{q}\" --group_fields {facets} --index_type whois-ip --format json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"facets":{"source":"query.facets","kind":"option","flag":"--group_fields","join":",","required":true},"size":{"source":"query.size","kind":"option","flag":"--size"},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"index_type":{"kind":"fixed","flag":"--index_type","value":"whois-ip"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/whois_domains/":{"get":{"tags":["Domain WHOIS"],"operationId":"domainWhoisSearch","security":[],"summary":"Domain WHOIS Search","description":"Searches for `q` in the selected `indices` and returns up to 20 search results, starting from the `start+1` document.\n \n❗️ This method allows retrieving only the first 10,000 search results.\n\nUse it when the expected number of results is relatively low or to craft and refine a query.\nUse the __Download__ endpoint to fetch results without pagination or quantity limitations.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"examples":{"domain":{"value":"example.com","description":"search for a specific domain"},"net_country":{"value":"registrant.organization:\"Meta Platforms\"","description":"domain registered to a specific organization"},"expirationDateExample":{"value":"expiration_date:[2025-01-01 TO 2025-01-31]","description":"domains expiring in 2023"}}},{"name":"start","in":"query","schema":{"$ref":"#/components/schemas/start"}},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices"}},{"name":"fields","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/fields"},"example":["registrant","registrar"]},{"name":"source_type","in":"query","schema":{"$ref":"#/components/schemas/source_type"}}],"responses":{"200":{"description":"__Search Results__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainWhoisSearch"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/whois_domains/\" \\\n -G \\\n --data-urlencode \"q=domain:example.com\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas search \"domain:example.com\" \\\n --datatype whois-domain \\\n --format json"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"domain:example.com\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nsearch_results = netlas_connection.search(\n query, datatype=\"whois-domain\"\n )\nprint(json.dumps(search_results))\n"}],"x-netlas-cli":{"supported":true,"tool":"search","template":"netlas search \"{q}\" --datatype whois-domain {field_selection} --format json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"fields":{"source":"query.fields","kind":"option","join":",","selector":"source_type","flags":{"include":"--include","exclude":"--exclude"}},"source_type":{"source":"query.source_type","kind":"selector","default":"include"},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"start":{"source":"query.start","unsupported":true,"reason":"Use CLI --page instead; the API start offset has no direct CLI equivalent."},"datatype":{"kind":"fixed","flag":"--datatype","value":"whois-domain"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/whois_domains_count/":{"get":{"tags":["Domain WHOIS"],"operationId":"domainWhoisCount","security":[],"summary":"Domain WHOIS Count","description":"Counts the number of documents matching the search query `q` in the selected `indices`.\n\n- If there are fewer than 1,000 results, the method returns the exact count.\n- If there are more than 1,000 results, the count is estimated with an error margin not exceeding 3%.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"example":"registrant.organization:\"Meta Platforms\""},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices"}}],"responses":{"200":{"description":"__Count__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Count"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/whois_domains_count/\" \\\n -G \\\n --data-urlencode 'q=registrant.organization:\"Meta Platforms\"' \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas count 'registrant.organization:\"Meta Platforms\"' \\\n --datatype whois-domain \\\n --format json"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = 'registrant.organization:\"Meta Platforms\"'\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\ncount_results = netlas_connection.count(\n query, datatype=\"whois-domain\"\n )\nprint(json.dumps(count_results))"}],"x-netlas-cli":{"supported":true,"tool":"count","template":"netlas count \"{q}\" --datatype whois-domain --format json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"datatype":{"kind":"fixed","flag":"--datatype","value":"whois-domain"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/whois_domains/download/":{"post":{"tags":["Domain WHOIS"],"operationId":"domainWhoisDownload","summary":"Domain WHOIS Download","description":"Retrieves `size` search results matching the query `q` in the selected `indices`.\n\nThe Netlas SDK and CLI tool additionally include a `download_all()` method and an `--all` key that allow you to query all available results.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadPayload"},"example":{"q":"registrant.organization:\"Meta Platforms\"","size":100,"fields":["domain","registrant","registrar","created_date","updated_date"],"source_type":"include"}}}},"responses":{"200":{"description":"__Search Results__","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/DomainWhoisDownloadJSON"},{"$ref":"#/components/schemas/DownloadCSV"}]},"example":[{"data":{"registrar":{"phone":"+1.6503087004","referral_url":"https://www.registrarsec.com","name":"RegistrarSEC, LLC","id":"2475","email":"abusecomplaints@registrarsec.com"},"stats":{"retries":0,"quota_retries":1,"parser":"no_error","was_queued":true,"error":"no_error","total_time":3212224099},"domain":"facebookinstagram.club","created_date":"2021-01-01T04:31:04.000Z","registrant":{"country":"US","province":"CA","phone":"+1.6505434800","city":"Menlo Park","street":"1601 Willow Rd","organization":"Meta Platforms, Inc.","id":"CFD32E1A5A4214BE1B361B507C8F159E1-NSR","postal_code":"94025"},"updated_date":"2024-10-08T09:00:11.000Z"}},{"data":{"registrar":{"phone":"+1.6503087004","referral_url":"https://www.registrarsec.com","name":"RegistrarSEC, LLC","id":"2475","email":"abusecomplaints@registrarsec.com"},"stats":{"retries":3,"quota_retries":2,"parser":"no_error","was_queued":false,"error":"no_error","total_time":61186643216},"domain":"playit.games","created_date":"2018-12-24T18:49:39.000Z","registrant":{"country":"US","province":"CA","phone":"+1.6505434800","city":"Menlo Park","street":"1601 Willow Rd","organization":"Meta Platforms, Inc.","id":"d2d0ffd8525b47ac980ed1b6cd94b53a-DONUTS","postal_code":"94025"},"updated_date":"2024-10-01T09:00:17.000Z"}},{"data":{"registrar":{"phone":"+1.6503087004","referral_url":"https://www.registrarsec.com","name":"RegistrarSEC, LLC","id":"2475","email":"abusecomplaints@registrarsec.com"},"stats":{"retries":0,"quota_retries":0,"parser":"no_error","was_queued":false,"error":"no_error","total_time":1640247726},"domain":"armature.biz","created_date":"2021-11-16T15:58:58.000Z","registrant":{"country":"US","province":"CA","phone":"+1.6505434800","city":"Menlo Park","street":"1601 Willow Rd","organization":"Meta Platforms, Inc.","id":"C4AA0F510959A485B9F6B98358B3A51B2-NSR","postal_code":"94025"},"updated_date":"2022-10-02T18:52:24.000Z"}},{"data":{"registrar":{"phone":"+1.6503087004","referral_url":"https://www.registrarsec.com","name":"RegistrarSEC, LLC","id":"2475","email":"abusecomplaints@registrarsec.com"},"stats":{"retries":3,"quota_retries":2,"parser":"no_error","was_queued":false,"error":"no_error","total_time":61653355239},"domain":"metaquest.engineering","created_date":"2022-01-27T19:41:55.000Z","registrant":{"country":"US","province":"CA","phone":"+1.6505434800","city":"Menlo Park","street":"1601 Willow Rd","organization":"Meta Platforms, Inc.","id":"71771827efe4428d9173f02838801b85-DONUTS","postal_code":"94025"},"updated_date":"2024-11-04T09:01:17.000Z"}},{"data":{"registrar":{"phone":"+1.6503087004","referral_url":"https://www.registrarsec.com","name":"RegistrarSEC, LLC","id":"2475","email":"abusecomplaints@registrarsec.com"},"stats":{"retries":1,"quota_retries":0,"parser":"no_error","was_queued":false,"error":"no_error","total_time":13076483862},"domain":"metabankbilling.mobi","created_date":"2017-03-01T18:16:53.000Z","registrant":{"country":"US","province":"CA","phone":"+1.6505434800","city":"Menlo Park","street":"1601 Willow Rd","organization":"Meta Platforms, Inc.","id":"dc3017e992ae43f4a17b2e75e0727f5c-DONUTS","postal_code":"94025"},"updated_date":"2024-12-07T09:00:32.000Z"}}]}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X POST \\\n \"https://app.netlas.io/api/whois_domains/download/\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -d '{\n \"q\": \"registrant.organization:\\\"Meta Platforms\\\"\",\n \"fields\": [\"domain\", \"registrant\", \"registrar\", \"created_date\", \"updated_date\"],\n \"size\": 100,\n \"source_type\": \"include\"\n }'\n "},{"lang":"Netlas CLI","source":"netlas download \"registrant.organization:\\\"Meta Platforms\\\"\" \\\n --datatype whois-domain \\\n --include domain,registrant,registrar,created_date,updated_date \\\n --count 100 # --all to download all results (no need to specify --count)\n "},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"registrant.organization:\\\"Meta Platforms\\\"\"\nfields = \"domain,registrant,registrar,created_date,updated_date\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n \nfor r in netlas_connection.download(\n query, fields, datatype=\"whois-domain\" ,size=100\n # use Netlas.download_all() to download all results\n # (no need to specify size parameter)\n ):\n response = json.loads(r.decode(\"utf-8\"))\n print(json.dumps(response))"}],"x-netlas-cli":{"supported":true,"tool":"download","template":"netlas download \"{q}\" --datatype whois-domain {field_selection} --count {size} --format json","args":{"q":{"source":"body.q","kind":"positional","position":0,"required":true},"fields":{"source":"body.fields","kind":"option","join":",","selector":"source_type","flags":{"include":"--include","exclude":"--exclude"}},"source_type":{"source":"body.source_type","kind":"selector","default":"include"},"size":{"source":"body.size","kind":"option","flag":"--count"},"indices":{"source":"body.indices","kind":"option","flag":"--indices","join":","},"datatype":{"kind":"fixed","flag":"--datatype","value":"whois-domain"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/whois_domains_facet/":{"get":{"tags":["Domain WHOIS"],"operationId":"domainWhoisFacet","security":[],"summary":"Domain WHOIS Facet Search","description":"Searches for `q` in the selected `indices` and groups results by the `facets` field.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"example":"level:2"},{"name":"facets","in":"query","required":true,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/facets"},"example":["zone"]},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices"}},{"name":"size","in":"query","schema":{"$ref":"#/components/schemas/facet_search_size"}}],"responses":{"200":{"description":"__Facet Search Results__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetSearchResults"},"example":{"aggregations":[{"key":["com"],"doc_count":377917162},{"key":["net"],"doc_count":21765983},{"key":["org"],"doc_count":19341321},{"key":["xyz"],"doc_count":13838761},{"key":["de"],"doc_count":12480920}]}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/whois_domains_facet/\" \\\n -G \\\n --data-urlencode 'q=level:2' \\\n --data-urlencode 'facets=zone' \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas facet 'registrant.organization:\"Meta Platforms\"' \\\n --group_fields registrant.organization \\\n --index_type whois-domain \\\n --format json\n"},{"lang":"Python","source":"import json\nimport netlas\n\nquery = 'registrant.organization:\"Meta Platforms\"'\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nresults = netlas_connection.stat(query, facets=\"registrant.organization\", index_type=\"whois-domain\")\nprint(json.dumps(results))\n"}],"x-netlas-cli":{"supported":true,"tool":"facet","template":"netlas facet \"{q}\" --group_fields {facets} --index_type whois-domain --format json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"facets":{"source":"query.facets","kind":"option","flag":"--group_fields","join":",","required":true},"size":{"source":"query.size","kind":"option","flag":"--size"},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"index_type":{"kind":"fixed","flag":"--index_type","value":"whois-domain"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/certs/":{"get":{"tags":["Certificates"],"operationId":"certsSearch","security":[],"summary":"Certificates Search","description":"Searches for `q` in the selected `indices` and returns up to 20 search results, starting from the `start+1` document.\n \n❗️ This method allows retrieving only the first 10,000 search results.\n\nUse it when the expected number of results is relatively low or to craft and refine a query.\nUse the __Download__ endpoint to fetch results without pagination or quantity limitations.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"example":"certificate.subject_dn:\"example.com\""},{"name":"start","in":"query","schema":{"$ref":"#/components/schemas/start"}},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices","example":null},"description":"ℹ️ Netlas stores all collected certificates in a single default index. \nThis parameter is included for interface consistency but is not applicable to certificate-related endpoints.\n"},{"name":"fields","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/fields"},"example":["*"]},{"name":"source_type","in":"query","schema":{"$ref":"#/components/schemas/source_type"}}],"responses":{"200":{"description":"__Search Results__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateSearch"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/certs/\" \\\n -G \\\n --data-urlencode \"q=certificate.subject_dn:example.com\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas search \"certificate.subject_dn:example.com\" \\\n --datatype cert \\\n --format json"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"certificate.subject_dn:example.com\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nsearch_results = netlas_connection.search(\n query, datatype=\"cert\"\n )\nprint(json.dumps(search_results))\n"}],"x-netlas-cli":{"supported":true,"tool":"search","template":"netlas search \"{q}\" --datatype cert {field_selection} --format json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"fields":{"source":"query.fields","kind":"option","join":",","selector":"source_type","flags":{"include":"--include","exclude":"--exclude"}},"source_type":{"source":"query.source_type","kind":"selector","default":"include"},"start":{"source":"query.start","unsupported":true,"reason":"Use CLI --page instead; the API start offset has no direct CLI equivalent."},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"datatype":{"kind":"fixed","flag":"--datatype","value":"cert"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/certs_count/":{"get":{"tags":["Certificates"],"operationId":"certsCount","security":[],"summary":"Certificates Count","description":"Counts the number of documents matching the search query `q` in the selected `indices`.\n\n- If there are fewer than 1,000 results, the method returns the exact count.\n- If there are more than 1,000 results, the count is estimated with an error margin not exceeding 3%.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"$ref":"#/components/schemas/q"},"example":"certificate.subject_dn:\"example.com\""},{"name":"indices","in":"query","required":false,"style":"form","explode":false,"schema":{"$ref":"#/components/schemas/indices","example":null},"description":"ℹ️ Netlas stores all collected certificates in a single default index. \nThis parameter is included for interface consistency but is not applicable to certificate-related endpoints.\n"}],"responses":{"200":{"description":"__Count__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Count"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/certs_count/\" \\\n -G \\\n --data-urlencode 'q=certificate.subject_dn:example.com' \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas count 'certificate.subject_dn:example.com' \\\n --datatype cert \\\n --format json"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"certificate.subject_dn:example.com\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\ncount_results = netlas_connection.count(\n query, datatype=\"cert\"\n )\nprint(json.dumps(count_results))"}],"x-netlas-cli":{"supported":true,"tool":"count","template":"netlas count \"{q}\" --datatype cert --format json","args":{"q":{"source":"query.q","kind":"positional","position":0,"required":true},"indices":{"source":"query.indices","kind":"option","flag":"--indices","join":","},"datatype":{"kind":"fixed","flag":"--datatype","value":"cert"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/certs/download/":{"post":{"tags":["Certificates"],"operationId":"certsDownload","summary":"Certificates Download","description":"Retrieves `size` search results matching the query `q` in the selected `indices`.\n\nThe Netlas SDK and CLI tool additionally include a `download_all()` method and an `--all` key that allow you to query all available results.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadPayload"},"example":{"q":"certificate.subject_dn:\"example.com\"","size":100,"fields":["src","subject_dn","fingerprint_sha256"],"source_type":"include"}}}},"responses":{"200":{"description":"__Search Results__","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CertificateDownloadJSON"},{"$ref":"#/components/schemas/DownloadCSV"}]},"example":[{"data":{"certificate":{"src":"https://example.com:443/","subject_dn":"CN=example.com","fingerprint_sha256":"25847d668eb4f04fdd40b12b6b0740c567da7d024308eb6c2c96fe41d9de218d"}}},{"data":{"certificate":{"src":"https://www.example.com:443/","subject_dn":"CN=www.example.com","fingerprint_sha256":"455943cf819425761d1f950263ebf54755d8d684c25535943976f488bc79d23b"}}}]}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X POST \\\n \"https://app.netlas.io/api/certs/download/\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -d '{\n \"q\": \"certificate.subject_dn:\\\"example.com\\\"\",\n \"fields\": [\"src\", \"subject_dn\", \"fingerprint_sha256\"],\n \"size\": 100,\n \"source_type\": \"include\"\n }'\n \n"},{"lang":"Netlas CLI","source":"netlas download \"certificate.subject_dn:\\\"example.com\\\"\" \\\n --datatype cert \\\n --include src,subject_dn,fingerprint_sha256 \\\n --count 100 # --all to download all results (no need to specify --count)\n \n"},{"lang":"Python","source":"import netlas\nimport json\n\nquery = \"certificate.subject_dn:\\\"example.com\\\"\"\nfields = \"src,subject_dn,fingerprint_sha256\"\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n \nfor r in netlas_connection.download(\n query, fields, datatype=\"cert\", size=100\n # use Netlas.download_all() to download all results\n # (no need to specify size parameter)\n ):\n response = json.loads(r.decode(\"utf-8\"))\n print(json.dumps(response))\n"}],"x-netlas-cli":{"supported":true,"tool":"download","template":"netlas download \"{q}\" --datatype cert {field_selection} --count {size} --format json","args":{"q":{"source":"body.q","kind":"positional","position":0,"required":true},"fields":{"source":"body.fields","kind":"option","join":",","selector":"source_type","flags":{"include":"--include","exclude":"--exclude"}},"source_type":{"source":"body.source_type","kind":"selector","default":"include"},"size":{"source":"body.size","kind":"option","flag":"--count"},"indices":{"source":"body.indices","kind":"option","flag":"--indices","join":","},"datatype":{"kind":"fixed","flag":"--datatype","value":"cert"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/indices/":{"get":{"tags":["Indices"],"operationId":"getIndices","security":[],"summary":"Get Indices","description":"Retrieve a list of indices accessible to the user.\n","responses":{"200":{"description":"__A List of Indices__","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/indice"}}}}},"400":{"$ref":"#/components/responses/INDICES_BAD_REQUEST"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"curl -X GET \"https://app.netlas.io/api/indices/\" \\\n -H \"content-type: application/json\""},{"lang":"Netlas CLI","source":"netlas indices -f json"},{"lang":"Python","source":"import netlas\nimport json\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nindices = netlas_connection.indices()\nprint(json.dumps(indices))"}],"x-netlas-cli":{"supported":true,"tool":"indices","template":"netlas indices -f json","args":{"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/mapping/{collection}/":{"get":{"tags":["Mapping"],"operationId":"getMapping","security":[],"summary":"Get Mapping","description":"Returns the field mapping for the default index in the `{collection}`.\n\nUse this mapping to understand which fields are available and how they are typed, \nso you can [craft precise search queries](/knowledge-base/query-language/) using Lucene Query Syntax.\n\nEach field or subfield will include either a `field_type` or `children` property:\n\n- A `field_type` indicates that the field is a leaf node in the mapping tree.\n- A `children` property indicates a parent field that contains nested fields.\n\nExample:\n```json\n{\n \"leaf\": {\n \"field_type\": \"type\"\n },\n \"parent\": {\n \"children\": [\n {\n \"leaf\": {\n \"field_type\": \"type\"\n }\n }\n ]\n }\n}\n```\n\n❗️__Note__: This endpoint returns the search mapping, which may slightly differ from the structure of actual search results.\nRefer to the response examples for each data collection to see how fields are represented in real-world data.\n","parameters":[{"name":"collection","in":"path","required":true,"description":"The collection for which mapping should be retrieved.\n","schema":{"$ref":"#/components/schemas/dataCollectionType"}}],"responses":{"200":{"description":"__Field Mapping__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mapping_response"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"404":{"$ref":"#/components/responses/NOT_FOUND"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"curl -X GET \\\n \"https://app.netlas.io/api/mapping/responses/\" \\\n -H \"content-type: application/json\""},{"lang":"Netlas CLI","source":"netlas mapping -d response -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nmapping_data = netlas_connection.mapping(datatype=\"response\", is_facet=False)\nprint(json.dumps(mapping_data))\n"}],"x-netlas-cli":{"supported":true,"tool":"mapping","template":"netlas mapping --datatype {collection} --format json","args":{"collection":{"source":"path.collection","kind":"option","flag":"--datatype","enumMap":{"responses":"response","domains":"domain","whois_ip":"whois-ip","whois_domains":"whois-domain"},"unsupportedValues":{"certs":"Current Netlas CLI mapping command does not support certificate mapping."},"required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/mapping/{collection}/facet/":{"get":{"tags":["Mapping"],"operationId":"getFacetMapping","security":[],"summary":"Get Facet Mapping","description":"Returns the facet-specific field mapping for the `{collection}`.\n\nThis mapping includes only fields that are suitable for use in **facet (group-by)** searches. \nNot all fields in the regular mapping can be used for aggregation, so fields that are not aggregatable \n(e.g., large text fields, arrays) are excluded from the facet mapping.\n\nUse this endpoint to discover which fields are available for grouping results in your search queries.\n","parameters":[{"name":"collection","in":"path","required":true,"description":"The collection for which facet mapping should be retrieved.\n","schema":{"$ref":"#/components/schemas/dataCollectionType"}}],"responses":{"200":{"description":"__Facet Field Mapping__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mapping_response"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"404":{"$ref":"#/components/responses/NOT_FOUND"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"curl -X GET \\\n \"https://app.netlas.io/api/mapping/responses/facet/\" \\\n -H \"content-type: application/json\""},{"lang":"Netlas CLI","source":"netlas mapping -d response --facet -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nfacet_mapping_data = netlas_connection.mapping(datatype=\"response\", is_facet=True)\nprint(json.dumps(facet_mapping_data))\n"}],"x-netlas-cli":{"supported":true,"tool":"mapping","template":"netlas mapping --datatype {collection} --facet --format json","args":{"collection":{"source":"path.collection","kind":"option","flag":"--datatype","enumMap":{"responses":"response","domains":"domain","whois_ip":"whois-ip","whois_domains":"whois-domain"},"unsupportedValues":{"certs":"Current Netlas CLI mapping command does not support certificate mapping."},"required":true},"facet":{"kind":"fixed","flag":"--facet","value":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/discovery/node_count/":{"post":{"tags":["Discovery"],"operationId":"getSearchesByNode","security":[],"summary":"Searches for a Node","description":"Retrieve a list of available searches for the specified node, defined by `node_value` and `node_type`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"node_type":{"$ref":"#/components/schemas/node_type"},"node_value":{"$ref":"#/components/schemas/node_value"}},"required":["node_type","node_value"]}}}},"responses":{"200":{"description":"__Available Searches__","headers":{"X-Count-Id":{"schema":{"$ref":"#/components/schemas/X-Count-Id"}}},"content":{"application/json":{"schema":{"type":"array","title":"Available Searches","description":"A list of aggregations containing available searches, the count of results for each search, \nand a preview of the results.\n","items":{"type":"object","properties":{"aggregations":{"$ref":"#/components/schemas/aggregations"}}}},"example":[{"aggregations":[{"search_field":"TXT records for domain","count":2,"preview":["_k2n1y4vw3qtb4skdx9e7dxt97qrmmq9","v=spf1 -all"],"search_field_id":32,"is_too_much_docs":false,"node_types":{"dns_txt":3}},{"search_field":"NS servers for domain","count":2,"preview":["elliott.ns.cloudflare.com","hera.ns.cloudflare.com"],"search_field_id":30,"is_too_much_docs":false,"node_types":{"domain":1}},{"search_field":"A records for domain","count":16,"preview":["8.6.112.0","8.6.112.6","8.6.112.8","8.6.112.10","8.47.69.0"],"search_field_id":29,"is_too_much_docs":false,"node_types":{"ip":0}}]},{"aggregations":[{"search_field":"Subdomains","count":92129,"preview":["0.example.com","0.vesta.example.com","000.example.com","0000-forbidden.example.com","0000107.example.com"],"search_field_id":35,"is_too_much_docs":false,"node_types":{"domain":1}}]},{"aggregations":[{"search_field":"Hosts with domain in certificate","count":72056,"preview":["34.81.108.244","178.81.31.44","161.97.104.183","130.162.41.25"],"search_field_id":47,"is_too_much_docs":false,"node_types":{"autodetect":13}}]}]}},"links":{"searchByNode":{"operationId":"searchByNode","parameters":{"X-Count-Id":"$response.header.X-Count-Id"},"requestBody":{"application/json":{"node_type":"$request.body#/node_type","node_value":"$request.body#/node_value","search_field_id":"$response.body#/0/search_field_id"}}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -i -X POST \\\n \"https://app.netlas.io/api/discovery/node_count/\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -d '{\n \"node_type\": \"domain\",\n \"node_value\": \"example.com\"\n }'"},{"lang":"Netlas CLI","source":"netlas discovery searches example.com -t domain -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\navailable_searches = netlas_connection.discovery_node_count(\n node_type=\"domain\",\n node_value=\"example.com\",\n)\nprint(json.dumps(available_searches))\n"}],"x-netlas-cli":{"supported":true,"tool":"discovery searches","template":"netlas discovery searches {node_value} --node-type {node_type} -f json","args":{"node_value":{"source":"body.node_value","kind":"positional","position":0,"required":true},"node_type":{"source":"body.node_type","kind":"option","flag":"--node-type","required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/discovery/node_result/":{"post":{"tags":["Discovery"],"operationId":"searchByNode","security":[],"summary":"Perform a Node Search","description":"Execute a search using `search_field_id` for a node specified by `node_value` and `node_type`, \nand retrieve the corresponding results.\n","parameters":[{"in":"header","name":"X-Count-Id","required":true,"description":"Perform a [`/api/discovery/node_count`](#tag/Discovery/operation/getSearchesByNode) request to get the `X-Count-Id`.\n","schema":{"$ref":"#/components/schemas/X-Count-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"node_type":{"$ref":"#/components/schemas/node_type"},"node_value":{"$ref":"#/components/schemas/node_value"},"search_field_id":{"$ref":"#/components/schemas/search_field_id"}},"required":["node_type","node_value","search_field_id"]}}}},"responses":{"200":{"description":"__Search Results__","content":{"application/json":{"schema":{"type":"object","properties":{"aggregations":{"type":"array","description":"Search results returned by related to the performed search aggregation.\n","items":{"$ref":"#/components/schemas/node_search_result"}}},"example":{"aggregations":[{"is_valid":true,"node_value":"23.192.228.80","node_type":"ip"},{"is_valid":true,"node_value":"23.192.228.84","node_type":"ip"}]}}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"if [ -z \"$1\" ]; then\n echo \"Error: Pass X-Count-Id as an argument\"\n exit 1\nfi\n\ncurl -s -X POST \\\n \"https://app.netlas.io/api/discovery/node_result/\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -H \"X-Count-Id: $1\" \\\n -d '{\n \"node_type\": \"domain\",\n \"node_value\": \"example.com\",\n \"search_field_id\": 29\n }'"},{"lang":"Netlas CLI","source":"netlas discovery fetch example.com 29 -t domain -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\nnode_type = \"domain\"\nnode_value = \"example.com\"\nsearch_field_id = 29\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\navailable_searches = netlas_connection.discovery_node_count(\n node_type=node_type,\n node_value=node_value,\n)\n\nresults = netlas_connection.discovery_node_result(\n x_count_id=available_searches[\"x_count_id\"],\n node_type=node_type,\n node_value=node_value,\n search_field_id=search_field_id,\n)\nprint(json.dumps(results))\n"}],"x-netlas-cli":{"supported":true,"workflow":[{"tool":"discovery searches","template":"netlas discovery searches {node_value} --node-type {node_type} -f json","produces":["search_field_id"]},{"tool":"discovery fetch","template":"netlas discovery fetch {node_value} {search_field_id} --node-type {node_type} -f json"}],"args":{"node_value":{"source":"body.node_value","kind":"positional","position":0,"required":true},"node_type":{"source":"body.node_type","kind":"option","flag":"--node-type","required":true},"search_field_id":{"source":"body.search_field_id","kind":"positional","position":1,"required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/discovery/group_of_nodes_count/":{"post":{"tags":["Discovery"],"operationId":"getSearchesByGroup","summary":"Searches for a Group","description":"Retrieve a list of available searches for a group of nodes, \nwhere each node is specified in `node_value` and must be of type `node_type`.\n\n⚠️ Retrieving results for large groups may take significant time.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"node_type":{"$ref":"#/components/schemas/node_type"},"node_value":{"type":"array","description":"A list of nodes.\n","items":{"$ref":"#/components/schemas/node_value"}}},"required":["node_type","node_value"]},"example":{"node_type":"domain","node_value":["example.com","example.org"]}}}},"responses":{"200":{"description":"__Stream of Available Searches__","headers":{"X-Count-Id":{"schema":{"$ref":"#/components/schemas/X-Count-Id"}},"X-Stream-Id":{"schema":{"$ref":"#/components/schemas/X-Stream-Id"}}},"content":{"application/x-ndjson":{"schema":{"type":"string","title":"Stream of Available Searches","description":"A stream of JSON objects, separated by the new line character, each containing searches available for this group. \nSee the sample below to understand the object's schema.\n\n```\n{\"search_field\": \"TXT records for domain\", \"count\": 2, \"preview\": [\"_k2n1y4vw3qtb4skdx9e7dxt97qrmmq9\", \"v=spf1 -all\"], \"search_field_id\": 32, \"is_too_much_docs\": false, \"node_types\": {\"dns_txt\": 3}}\n{\"search_field\": \"NS servers for domain\", \"count\": 2, \"preview\": [\"elliott.ns.cloudflare.com\", \"hera.ns.cloudflare.com\"], \"search_field_id\": 30, \"is_too_much_docs\": false, \"node_types\": {\"domain\": 1}}\n{\"search_field\": \"A records for domain\", \"count\": 16, \"preview\": [\"8.6.112.0\", \"8.6.112.6\", \"8.6.112.8\", \"8.6.112.10\", \"8.47.69.0\"], \"search_field_id\": 29, \"is_too_much_docs\": false, \"node_types\": {\"ip\": 0}}\n{\"search_field\": \"Subdomains\", \"count\": 92129, \"preview\": [\"0.example.com\", \"0.vesta.example.com\", \"000.example.com\", \"0000-forbidden.example.com\", \"0000107.example.com\"], \"search_field_id\": 35, \"is_too_much_docs\": false, \"node_types\": {\"domain\": 1}}\n{\"search_field\": \"Hosts with domain in certificate\", \"count\": 72056, \"preview\": [\"34.81.108.244\", \"178.81.31.44\", \"161.97.104.183\", \"130.162.41.25\"], \"search_field_id\": 47, \"is_too_much_docs\": false, \"node_types\": {\"autodetect\": 13}}\n```\n","example":"{\"search_field\": \"TXT records for domain\", \"count\": 2, \"preview\": [\"_k2n1y4vw3qtb4skdx9e7dxt97qrmmq9\", \"v=spf1 -all\"], \"search_field_id\": 32, \"is_too_much_docs\": false, \"node_types\": {\"dns_txt\": 3}}\n{\"search_field\": \"NS servers for domain\", \"count\": 2, \"preview\": [\"elliott.ns.cloudflare.com\", \"hera.ns.cloudflare.com\"], \"search_field_id\": 30, \"is_too_much_docs\": false, \"node_types\": {\"domain\": 1}}\n{\"search_field\": \"A records for domain\", \"count\": 16, \"preview\": [\"8.6.112.0\", \"8.6.112.6\", \"8.6.112.8\", \"8.6.112.10\", \"8.47.69.0\"], \"search_field_id\": 29, \"is_too_much_docs\": false, \"node_types\": {\"ip\": 0}}\n"}}},"links":{"getGroupRequestStatus":{"operationId":"getGroupRequestStatus","parameters":{"stream-id":"$response.header.X-Stream-Id"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -i -X POST \\\n \"https://app.netlas.io/api/discovery/group_of_nodes_count/\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -d '{\n \"node_type\": \"domain\",\n \"node_value\": [\"example.com\", \"example.org\"]\n }'"},{"lang":"Netlas CLI","source":"netlas discovery searches \"example.com,example.org\" -t domain -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\navailable_searches = netlas_connection.discovery_group_count(\n node_type=\"domain\",\n node_value=[\"example.com\", \"example.org\"],\n)\nprint(json.dumps(available_searches))\n"}],"x-netlas-cli":{"supported":true,"tool":"discovery searches","template":"netlas discovery searches {node_value} --node-type {node_type} -f json","args":{"node_value":{"source":"body.node_value","kind":"positional","position":0,"required":true,"style":"comma-separated"},"node_type":{"source":"body.node_type","kind":"option","flag":"--node-type","required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/discovery/group_of_nodes_result/":{"post":{"tags":["Discovery"],"operationId":"searchByGroup","summary":"Perform a Group Search","description":"Execute a search using `search_field_id` for a group of nodes specified in `node_value`, \nand retrieve the corresponding results.\n\n⚠️ Retrieving results for large groups may take significant time.\n","parameters":[{"in":"header","name":"X-Count-Id","required":true,"description":"Perform a [`/api/discovery/group_of_nodes_count`](#tag/Discovery/operation/getSearchesByGroup) request to get the `X-Count-Id`.\n","schema":{"$ref":"#/components/schemas/X-Count-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"node_type":{"$ref":"#/components/schemas/node_type"},"node_value":{"type":"array","description":"A list of nodes.\n","items":{"$ref":"#/components/schemas/node_value"}},"search_field_id":{"$ref":"#/components/schemas/search_field_id"}},"required":["node_type","node_value","search_field_id"]},"example":{"node_type":"domain","node_value":["example.com","example.org"],"search_field_id":29}}}},"responses":{"200":{"description":"__Stream of Results__","headers":{"X-Stream-Id":{"schema":{"$ref":"#/components/schemas/X-Stream-Id"}}},"content":{"application/x-ndjson":{"schema":{"type":"string","title":"Stream of Search Results","description":"A stream of JSON objects, separated by the new line character, each containing search results for a node. \nSee the sample below to understand the object's schema.\n\n```\n{\"node_key\": \"example.org\", \"aggregations\": [{\"is_valid\": true, \"node_value\": \"104.18.2.24\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"104.18.3.24\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"40.89.128.172\", \"node_type\": \"ip\"}]}\n{\"node_key\": \"example.com\", \"aggregations\": [{\"is_valid\": true, \"node_value\": \"104.18.27.120\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"104.18.26.120\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.6.112.0\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.47.69.0\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.47.69.10\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.6.112.10\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.74.138.66\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.88.251.189\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.88.128.4\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.88.198.69\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.88.198.68\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.47.69.8\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.6.112.8\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.6.112.6\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.47.69.6\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"23.227.38.74\", \"node_type\": \"ip\"}]}\n\n```\n","example":"{\"node_key\": \"example.org\", \"aggregations\": [{\"is_valid\": true, \"node_value\": \"104.18.2.24\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"104.18.3.24\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"40.89.128.172\", \"node_type\": \"ip\"}]}\n{\"node_key\": \"example.com\", \"aggregations\": [{\"is_valid\": true, \"node_value\": \"104.18.27.120\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"104.18.26.120\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.6.112.0\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.47.69.0\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.47.69.10\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.6.112.10\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.74.138.66\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.88.251.189\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.88.128.4\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.88.198.69\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"47.88.198.68\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.47.69.8\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.6.112.8\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.6.112.6\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"8.47.69.6\", \"node_type\": \"ip\"}, {\"is_valid\": true, \"node_value\": \"23.227.38.74\", \"node_type\": \"ip\"}]}\n"}}},"links":{"getGroupRequestStatus":{"operationId":"getGroupRequestStatus","parameters":{"stream-id":"$response.header.X-Stream-Id"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"429":{"$ref":"#/components/responses/TOO_MANY_REQUESTS"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"},"504":{"$ref":"#/components/responses/TIMEOUT"}},"x-codeSamples":[{"lang":"Curl","source":"if [ -z \"$1\" ]; then\n echo \"Error: Pass X-Count-Id as an argument\"\n exit 1\nfi\n\ncurl -s -X POST \\\n \"https://app.netlas.io/api/discovery/group_of_nodes_result/\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -H \"X-Count-Id: $1\" \\\n -d '{\n \"node_type\": \"domain\",\n \"node_value\": [\"example.com\", \"example.org\"],\n \"search_field_id\": 29\n }'"},{"lang":"Netlas CLI","source":"netlas discovery fetch \"example.com,example.org\" 29 -t domain -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\nnode_type = \"domain\"\nnode_value = [\"example.com\", \"example.org\"]\nsearch_field_id = 29\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\navailable_searches = netlas_connection.discovery_group_count(\n node_type=node_type,\n node_value=node_value,\n)\n\nresults = netlas_connection.discovery_group_result(\n x_count_id=available_searches[\"x_count_id\"],\n node_type=node_type,\n node_value=node_value,\n search_field_id=search_field_id,\n)\nprint(json.dumps(results))\n"}],"x-netlas-cli":{"supported":true,"workflow":[{"tool":"discovery searches","template":"netlas discovery searches {node_value} --node-type {node_type} -f json","produces":["search_field_id"]},{"tool":"discovery fetch","template":"netlas discovery fetch {node_value} {search_field_id} --node-type {node_type} -f json"}],"args":{"node_value":{"source":"body.node_value","kind":"positional","position":0,"required":true,"style":"comma-separated"},"node_type":{"source":"body.node_type","kind":"option","flag":"--node-type","required":true},"search_field_id":{"source":"body.search_field_id","kind":"positional","position":1,"required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/discovery/status/{stream-id}/":{"get":{"tags":["Discovery"],"operationId":"getGroupRequestStatus","summary":"Check Search Status","description":"Retrieve the current status of an ongoing group search operation:\n[fetching available searches for a group](#tag/Discovery/operation/getSearchesByGroup) \nor [executing a search for a group](#tag/Discovery/operation/searchByGroup).\n","parameters":[{"in":"path","name":"stream-id","required":true,"schema":{"$ref":"#/components/schemas/X-Stream-Id"}}],"responses":{"200":{"description":"__Search Status__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/stream_status_data"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"404":{"$ref":"#/components/responses/NOT_FOUND"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-netlas-cli":{"supported":true,"tool":"discovery status","template":"netlas discovery status --stream-id {stream-id} -f json","args":{"stream-id":{"source":"path.stream-id","kind":"option","flag":"--stream-id","required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/scanner/":{"get":{"tags":["Scanner"],"summary":"Get Scans","description":"Retrieve a list of private scans available to the user.","operationId":"getScans","parameters":[{"name":"own_scans_only","in":"query","description":"Filter to return only the scans owned by the user","required":false,"schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"__Private Scans__","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/private_scan"}}}},"links":{"getScan":{"operationId":"getScan","parameters":{"id":"$response.body#/0/id"}},"getScanReport":{"operationId":"getScanReport","parameters":{"id":"$response.body#/0/id"}},"updateScan":{"operationId":"updateScan","parameters":{"id":"$response.body#/0/id"}},"deleteScan":{"operationId":"deleteScan","parameters":{"id":"$response.body#/0/id"}}}},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \"https://app.netlas.io/api/scanner/\" \\\n -H \"content-type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas scanner list -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nscans = netlas_connection.scans()\nprint(json.dumps(scans))\n"}],"x-netlas-cli":{"supported":true,"tool":"scanner list","template":"netlas scanner list -f json","args":{"own_scans_only":{"source":"query.own_scans_only","unsupported":true,"reason":"Current Netlas CLI scanner list command does not expose own_scans_only."},"format":{"kind":"fixed","flag":"--format","value":"json"}}}},"post":{"tags":["Scanner"],"summary":"Create Scan","description":"Create and initiate a new private scan.","operationId":"scan","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"$ref":"#/components/schemas/scan_name"},"agent_id":{"$ref":"#/components/schemas/agent_id"},"targets":{"$ref":"#/components/schemas/targets"},"saved_graph_id":{"type":"string","description":"Identifier of the saved attack surface graph to scan."},"version":{"type":"integer","description":"Saved graph version."}},"anyOf":[{"required":["targets"]},{"required":["saved_graph_id","version"]}]}}}},"responses":{"201":{"description":"__Scan Created__","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/private_scan"}}}},"links":{"getScan":{"operationId":"getScan","parameters":{"id":"$response.body#/0/id"}},"getScanReport":{"operationId":"getScanReport","parameters":{"id":"$response.body#/0/id"}},"changeScanPriority":{"operationId":"changeScanPriority","requestBody":{"application/json":{"id":"$response.body#/0/id","shift":1}}},"updateScan":{"operationId":"updateScan","parameters":{"id":"$response.body#/0/id"}},"deleteScan":{"operationId":"deleteScan","parameters":{"id":"$response.body#/0/id"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"402":{"$ref":"#/components/responses/PAYMENT_REQUIRED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"curl -X POST \"https://app.netlas.io/api/scanner/\" \\\n -H \"content-type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -d '{\n \"targets\": [\n \"example.com\",\n \"23.215.0.136\"\n ],\n \"name\": \"My Private Scan\",\n \"agent_id\": 5\n }'\n"},{"lang":"Netlas CLI","source":"netlas scanner create --targets \"example.com,23.215.0.136\" --name \"My Private Scan\" --agent-id 5 -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\ncreated = netlas_connection.scan_create(targets=\"example.com,23.215.0.136\", name=\"My Private Scan\", agent_id=5)\nprint(json.dumps(created))\n"}],"x-netlas-cli":{"supported":true,"tool":"scanner create","template":"netlas scanner create --targets \"{targets}\" --name \"{name}\" --agent-id {agent_id} -f json","args":{"name":{"source":"body.name","kind":"option","flag":"--name","required":true},"agent_id":{"source":"body.agent_id","kind":"option","flag":"--agent-id","required":false},"targets":{"source":"body.targets","kind":"option","flag":"--targets","join":","},"saved_graph_id":{"source":"body.saved_graph_id","unsupported":true,"reason":"Current Netlas CLI scanner create command does not support saved_graph_id workflows."},"version":{"source":"body.version","unsupported":true,"reason":"Current Netlas CLI scanner create command does not support saved graph version workflows."},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/scanner/agents/":{"get":{"tags":["Scanner"],"summary":"Get Scanner Agents","description":"Retrieve the list of scanner agents available for initiating private scans from different geolocations.","operationId":"getScannerAgents","responses":{"200":{"description":"__Scanner Agents__","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/scanner_agent"}}}},"links":{"scan":{"operationId":"scan","requestBody":{"application/json":{"agent_id":"$response.body#/0/id","name":"My Private Scan","targets":["example.com"]}}}}},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"curl -X GET \"https://app.netlas.io/api/scanner/agents/\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\"\n"},{"lang":"Python","source":"import json\nimport requests\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\n\nresponse = requests.get(\n \"https://app.netlas.io/api/scanner/agents/\",\n headers={\"Authorization\": f\"Bearer {api_key}\"},\n)\nresponse.raise_for_status()\nprint(json.dumps(response.json()))\n"}],"x-netlas-cli":{"supported":false,"reason":"Current Netlas CLI does not expose scanner agent listing."}}},"/api/scanner/{id}/":{"get":{"tags":["Scanner"],"summary":"Get Scan","description":"Retrieve detailed information about a private scan using its `id`.","operationId":"getScan","parameters":[{"name":"id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/scan_id"}}],"responses":{"200":{"description":"__Scan Details__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/private_scan"}}},"links":{"getScanReport":{"operationId":"getScanReport","parameters":{"id":"$response.body#/id"}}}},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"404":{"$ref":"#/components/responses/SCANNER_NOT_FOUND"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"if [ -z \"$1\" ]; then\n echo \"Error: Pass scan ID as an argument\"\n exit 1\nfi\n\ncurl -X GET \"https://app.netlas.io/api/scanner/$1/\" \\\n -H \"content-type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas scanner get 123 -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\ncreated = netlas_connection.scan_create(\n targets=\"scanme.nmap.org\",\n name=\"SDK Example: scan_get\",\n)\nscan_id = created[0][\"id\"]\n\ntry:\n scan = netlas_connection.scan_get(id=scan_id)\n print(json.dumps(scan))\nfinally:\n netlas_connection.scan_delete(id=scan_id)\n"}],"x-netlas-cli":{"supported":true,"tool":"scanner get","template":"netlas scanner get {id} -f json","args":{"id":{"source":"path.id","kind":"positional","position":0,"required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}},"patch":{"tags":["Scanner"],"summary":"Update Scan","description":"Update the label of a private scan using its `id`.","operationId":"updateScan","parameters":[{"name":"id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/scan_id"}}],"requestBody":{"description":"The new label for the scan","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/scan_name","description":"New label for the scan"}}},"example":{"name":"Updated scan name"}}}},"responses":{"200":{"description":"__Scan Updated__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/private_scan"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"404":{"$ref":"#/components/responses/SCANNER_NOT_FOUND"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"if [ -z \"$1\" ]; then\n echo \"Error: Pass scan ID as an argument\"\n exit 1\nfi\n\ncurl -X 'PATCH' \"https://app.netlas.io/api/scanner/$1/\" \\\n -H \"content-type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -d '{\"name\": \"New Scan Label\"}'\n"},{"lang":"Netlas CLI","source":"netlas scanner rename --id 123 --name \"New Scan Label\" -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\ncreated = netlas_connection.scan_create(\n targets=\"scanme.nmap.org\",\n name=\"SDK Example: original label\",\n)\nscan_id = created[0][\"id\"]\n\ntry:\n renamed = netlas_connection.scan_rename(id=scan_id, name=\"SDK Example: new label\")\n print(json.dumps(renamed))\nfinally:\n netlas_connection.scan_delete(id=scan_id)\n"}],"x-netlas-cli":{"supported":true,"tool":"scanner rename","template":"netlas scanner rename --id {id} --name \"{name}\" -f json","args":{"id":{"source":"path.id","kind":"option","flag":"--id","required":true},"name":{"source":"body.name","kind":"option","flag":"--name","required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}},"delete":{"tags":["Scanner"],"summary":"Delete Scan","description":"Permanently remove a private scan using its `id`.","operationId":"deleteScan","parameters":[{"name":"id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/scan_id"}}],"responses":{"204":{"description":"__Scan Deleted__"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"404":{"$ref":"#/components/responses/SCANNER_NOT_FOUND"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"if [ -z \"$1\" ]; then\n echo \"Error: Pass scan ID as an argument\"\n exit 1\nfi\n\ncurl -X 'DELETE' \"https://app.netlas.io/api/scanner/$1/\" \\\n -H \"content-type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas scanner delete --id 123 -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\ncreated = netlas_connection.scan_create(\n targets=\"scanme.nmap.org\",\n name=\"SDK Example: scan_delete\",\n)\nscan_id = created[0][\"id\"]\n\ndeleted = netlas_connection.scan_delete(id=scan_id)\nprint(json.dumps(deleted))\n"}],"x-netlas-cli":{"supported":true,"tool":"scanner delete","template":"netlas scanner delete --id {id} -f json","args":{"id":{"source":"path.id","kind":"option","flag":"--id","required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/scanner/{id}/report/":{"get":{"tags":["Scanner"],"summary":"Get Scan Report","description":"Retrieve the JSON report generated for a private scan using its `id`.","operationId":"getScanReport","parameters":[{"name":"id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/scan_id"}}],"responses":{"200":{"description":"__Scan Report__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/scan_report"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"403":{"$ref":"#/components/responses/ACCESS_DENIED"},"404":{"$ref":"#/components/responses/SCANNER_NOT_FOUND"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"if [ -z \"$1\" ]; then\n echo \"Error: Pass scan ID as an argument\"\n exit 1\nfi\n\ncurl -s -X GET \"https://app.netlas.io/api/scanner/$1/report/\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -H \"Accept: application/json\"\n"},{"lang":"Netlas CLI","source":"netlas scanner report --id 123 -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\nscan_id = 123\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nreport = netlas_connection.get_scan_report(id=scan_id)\n\nprint(json.dumps(report))\n"}],"x-netlas-cli":{"supported":true,"tool":"scanner report","template":"netlas scanner report --id {id} -f json","args":{"id":{"source":"path.id","kind":"option","flag":"--id","required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/scanner/change_priority/":{"post":{"tags":["Scanner"],"summary":"Change Scan Priority","description":"Modify the priority of a private scan with `id` in the processing queue by shifting it `shift` positions.\n\nℹ️ This adjustment applies only to scans with the `Pending` status. \nScans that are already scheduled or in progress will not be affected.\n","operationId":"changeScanPriority","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","shift"],"properties":{"id":{"$ref":"#/components/schemas/scan_id"},"shift":{"$ref":"#/components/schemas/shift"}}}}}},"responses":{"200":{"description":"__Priority Changed__","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/private_scan"}}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"404":{"$ref":"#/components/responses/SCANNER_NOT_FOUND"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"if [ -z \"$1\" ]; then\n echo \"Error: Pass scan ID as an argument\"\n exit 1\nfi\n\ncurl -X 'POST' \\\n \"https://app.netlas.io/api/scanner/change_priority/\" \\\n -H \"content-type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -d '{\"id\": '\"$1\"', \"shift\":'-1'}'"},{"lang":"Netlas CLI","source":"netlas scanner priority --id 123 --shift -1 -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\ncreated = netlas_connection.scan_create(\n targets=\"scanme.nmap.org\",\n name=\"SDK Example: scan_priority\",\n)\nscan_id = created[0][\"id\"]\n\ntry:\n updated = netlas_connection.scan_priority(id=scan_id, shift=-1)\n print(json.dumps(updated))\nfinally:\n netlas_connection.scan_delete(id=scan_id)\n"}],"x-netlas-cli":{"supported":true,"tool":"scanner priority","template":"netlas scanner priority --id {id} --shift {shift} -f json","args":{"id":{"source":"body.id","kind":"option","flag":"--id","required":true},"shift":{"source":"body.shift","kind":"option","flag":"--shift","required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/scanner/bulk_delete/":{"post":{"tags":["Scanner"],"summary":"Bulk Delete Scans","description":"Delete multiple private scans using their respective `id` values.","operationId":"deleteScans","requestBody":{"description":"The list of scan IDs to delete","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","description":"List of scan IDs to delete","items":{"$ref":"#/components/schemas/scan_id"}}}}}}},"responses":{"204":{"description":"__Scans Deleted__"},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"404":{"$ref":"#/components/responses/SCANNER_NOT_FOUND"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"if [ -z \"$1\" ] || [ -z \"$2\" ]; then\n echo \"Error: Pass two scan ID as arguments\"\n exit 1\nfi\n\ncurl -X POST \"https://app.netlas.io/api/scanner/bulk_delete/\" \\\n -H \"content-type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -d '{ \"ids\": ['\"$1\"', '\"$2\"'] }'"},{"lang":"Netlas CLI","source":"netlas scanner delete --id 123,456 -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\ncreated_a = netlas_connection.scan_create(\n targets=\"scanme.nmap.org\",\n name=\"SDK Example: bulk_delete A\",\n)\ncreated_b = netlas_connection.scan_create(\n targets=\"scanme.nmap.org\",\n name=\"SDK Example: bulk_delete B\",\n)\nscan_ids = [created_a[0][\"id\"], created_b[0][\"id\"]]\n\ndeleted = netlas_connection.scan_bulk_delete(ids=scan_ids)\nprint(json.dumps(deleted))\n"}],"x-netlas-cli":{"supported":true,"tool":"scanner delete","template":"netlas scanner delete --id {ids} -f json","args":{"ids":{"source":"body.ids","kind":"option","flag":"--id","join":",","required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/datastore/products/":{"get":{"tags":["Datastore"],"operationId":"getProducts","security":[],"summary":"Get Products","description":"Retrieve a list of published datasets available in the Netlas Datastore.\n","responses":{"200":{"description":"__Published Products__","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DatastoreProduct"}}}},"links":{"getProduct":{"operationId":"getProduct","parameters":{"id":"$response.body#/0/id"}},"getProductLink":{"operationId":"getProductLink","parameters":{"id":"$response.body#/0/id"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/datastore/products/\" \\\n -H \"content-type: application/json\""},{"lang":"Netlas CLI","source":"netlas datastore list -f json"},{"lang":"Python","source":"import netlas\nimport json\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\ndatasets = netlas_connection.datasets()\nprint(json.dumps(datasets))\n"}],"x-netlas-cli":{"supported":true,"tool":"datastore list","template":"netlas datastore list -f json","args":{"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/datastore/products/{id}/":{"get":{"tags":["Datastore"],"operationId":"getProduct","security":[],"summary":"Get Product","description":"Retrieve details of a specific dataset from the Netlas Datastore.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/product_id"}}],"responses":{"200":{"description":"__A Single Product__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreProduct"}}}},"404":{"$ref":"#/components/responses/NOT_FOUND","description":"__Not Found__: The requested product does not exist or could not be found.\n"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/datastore/products/115/\" \\\n -H \"content-type: application/json\"\n"},{"lang":"Netlas CLI","source":"netlas datastore list 115 -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nproduct = netlas_connection.dataset_info(id=115)\nprint(json.dumps(product))\n"}],"x-netlas-cli":{"supported":true,"tool":"datastore list","template":"netlas datastore list {id} -f json","args":{"id":{"source":"path.id","kind":"positional","position":0,"required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/datastore/get_dataset_link/{id}/":{"get":{"tags":["Datastore"],"operationId":"getProductLink","summary":"Get Dataset Link","description":"Retrieve a download link for a product from the Netlas Datastore.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/product_id"}}],"responses":{"200":{"description":"__Download Links__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetLinks"}}}},"401":{"$ref":"#/components/responses/DATASTORE_UNAUTHORIZED"},"402":{"$ref":"#/components/responses/DATASTORE_PAYMENT_REQUIRED"},"404":{"$ref":"#/components/responses/NOT_FOUND","description":"__Not Found__: The requested product does not exist or could not be found.\n"}},"x-codeSamples":[{"lang":"Curl","source":"curl -s -X GET \\\n \"https://app.netlas.io/api/datastore/get_dataset_link/28/\" \\\n -H \"content-type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas datastore get 28 -f json"},{"lang":"Python","source":"import netlas\nimport json\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nlinks = netlas_connection.get_dataset_link(28)\nprint(json.dumps(links))\n"}],"x-netlas-cli":{"supported":true,"tool":"datastore get","template":"netlas datastore get {id} -f json","args":{"id":{"source":"path.id","kind":"positional","position":0,"required":true},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/users/current/":{"get":{"tags":["Users"],"operationId":"getUser","summary":"Get User Profile","description":"Retrieve profile details of the currently authenticated user.\n","responses":{"200":{"description":"__Profile Data__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user_profile"}}}},"400":{"$ref":"#/components/responses/USERS_BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"curl -X GET \"https://app.netlas.io/api/users/current/\" \\\n -H \"content-type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\""},{"lang":"Netlas CLI","source":"netlas profile info -f json\n"},{"lang":"Python","source":"import netlas\nimport json\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nprofile = netlas_connection.profile()\nprint(json.dumps(profile))"}],"x-netlas-cli":{"supported":true,"tool":"profile info","template":"netlas profile info -f json","args":{"format":{"kind":"fixed","flag":"--format","value":"json"}}}},"patch":{"tags":["Users"],"operationId":"updateUser","summary":"Update User Profile","description":"Modify the profile details of the currently authenticated user.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/user_profile_patch"},"examples":{"nameAndLastNameExample":{"summary":"Name & Last Name","description":"name and last name","value":{"first_name":"John","last_name":"Doe"}},"firstNameOnlyExample":{"summary":"First Name Only","description":"first name only","value":{"first_name":"John"}}}}}},"responses":{"200":{"description":"__Profile Data__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user_profile"}}}},"400":{"$ref":"#/components/responses/USERS_BAD_REQUEST"},"401":{"$ref":"#/components/responses/UNAUTHORIZED"},"403":{"$ref":"#/components/responses/USERS_ACCESS_DENIED"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"curl -X PATCH \"https://app.netlas.io/api/users/current/\" \\\n -H \"content-type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\" \\\n -d '{\n \"first_name\": \"John\",\n \"last_name\": \"Doe\"\n }'"},{"lang":"Netlas CLI","source":"netlas profile update --first \"John\" --last \"Doe\" -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\nprofile = netlas_connection.update_profile(first_name=\"John\", last_name=\"Doe\")\nprint(json.dumps(profile))\n"}],"x-netlas-cli":{"supported":true,"tool":"profile update","template":"netlas profile update --first {first_name} {last_name_flag} -f json","args":{"first_name":{"source":"body.first_name","kind":"option","flag":"--first","required":true},"last_name":{"source":"body.last_name","kind":"option","flag":"--last"},"format":{"kind":"fixed","flag":"--format","value":"json"}}}}},"/api/users/profile_data/":{"get":{"tags":["Users"],"operationId":"getUserCounters","security":[],"summary":"Get User Counters","description":"Retrieve user profile counters, including request limits and Netlas Coins balance.\nThis endpoint is public, but authenticated requests may return additional counters.\n","responses":{"200":{"description":"__Profile Data__","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user_counters"}}}},"400":{"$ref":"#/components/responses/USERS_BAD_REQUEST"},"500":{"$ref":"#/components/responses/INTERNAL_SERVER_ERROR"}},"x-codeSamples":[{"lang":"Curl","source":"curl -X GET \"https://app.netlas.io/api/users/profile_data/\" \\\n -H \"content-type: application/json\" \\\n -H \"Authorization: Bearer $NETLAS_API_KEY\"\n "},{"lang":"Netlas CLI","source":"netlas profile counters -f json\n"},{"lang":"Python","source":"import json\nimport netlas\n\napi_key = netlas.helpers.get_api_key()\nnetlas_connection = netlas.Netlas(api_key)\n\ncounters = netlas_connection.profile_data()\nprint(json.dumps(counters))\n"}],"x-netlas-cli":{"supported":true,"tool":"profile counters","template":"netlas profile counters -f json","args":{"format":{"kind":"fixed","flag":"--format","value":"json"}}}}}}}},"options":{"scrollYOffset":48,"hideLogo":true,"hideSecuritySection":true,"showExtensions":false,"disableSearch":true,"hideFab":true,"theme":{"breakpoints":{"medium":"84em","small":"60em"},"sidebar":{"width":"12rem"},"rightPanel":{"width":"45%"},"typography":{"fontFamily":"Roboto, sans-serif","fontSize":".8rem","lineHeight":"1.6","headings":{"fontFamily":"Roboto, sans-serif"},"code":{"fontFamily":"JetBrainsMono, monospace","fontSize":".85em","lineHeight":"1.4"},"optimizeSpeed":true,"smoothing":"antialiased"}}}}; var container = document.getElementById('redoc'); Redoc.hydrate(__redoc_state, container);