Assets

Find Assets

Find assets in a project using filters passed as query parameters. A more lightweight alternative to POST /_search for simpler queries.

Some query parameters are not filters but control pagination, sorting and returned fields:

cursor: The meta.pagination.next_cursor value from the previous response. Sorting can't be changed while paginating.
limit: The number of assets to return
sort_by, sort_direction: The field and direction to sort by
additional_fields: Enrichments to include in the response, repeated or comma-separated. By default only custom_tags is returned; specifying this replaces that default.

get/projects/{project_id}/assets

Request

Base URL
https://api.securitytrails.com/v2
URL
https://api.securitytrails.com/v2/projects/{project_id}/assets
Auth
API key in header apikey

Path parameters

project_idstring required

The ID of the project

Query parameters

limitinteger

The number of assets to return

The field to sort by

sort_direction'asc' | 'desc'

The direction to sort by

asset_typestring

The type of asset (ip or domain/host)

custom_tagsstring nullable

User-defined tags on the asset

custom_tags_strictstring nullable

User-defined tags on the asset, matched by exact (case-sensitive) title

has_custom_tagsboolean nullable

Filter for assets that have at least one custom tag applied. Overrides any other custom tag filtering specified.

added_to_project_beforestring date nullable

The date (Y-m-d) the asset was added to the project. This may be different than when the asset was discovered.

added_to_project_afterstring date nullable

The date (Y-m-d) the asset was added to the project. This may be different than when the asset was discovered.

discovered_beforestring date nullable

The date (Y-m-d) the asset was discovered. This may be different than when the asset was added to the project. IPv4 addresses will have a fixed point in the past for their discovery date.

discovered_afterstring date nullable

The date (Y-m-d) the asset was discovered. This may be different than when the asset was added to the project. IPv4 addresses will have a fixed point in the past for their discovery date.

apexstring nullable

The apex domain of the assets. Only makes sense for domain asset types.

Example:example.com

referenced_ipstring ipvanynetwork nullable

IP address referenced via A or CNAME record. Use eq or in for exact IP matching. Use contains with a trailing . for CIDR range matching, or without for prefix matching.

referenced_ip_beforestring date nullable

If filtering on a referenced_ip, include additional criteria that the record existed during a date range. In this case, the reference must have started before this date.

referenced_ip_afterstring date nullable

If filtering on a referenced_ip, include additional criteria that the record existed during a date range. In this case, the referenced must have existing after this date.

has_dns_record_typestring nullable

The type of DNS record, e.g. A, AAAA or CNAME

dns_resolvesboolean nullable

Filter for assets that in the end resolve to a valid IP currently, either via an A or CNAME. IP-assets is included when filtering for assets that resolve.

asninteger nullable

Autonomous System Number of the asset's IP

Example:16509

cname_referencestring nullable

Filter on a domain that is referenced by a CNAME record. Only makes sense for domain asset types. Treated as a wildcard, so example.com will match www.example.com.

geo_country_isostring nullable

ISO country code of the IP geo location

Example:US

ip_ownerstring nullable

Organization owning the IP address block

whois_emailstring email nullable

Email address of any current or historical WHOIS contact record, falling back to the parent domain's record

whois_email_currentstring email nullable

Email address of a WHOIS contact record, falling back to the parent domain's record

open_port_numberinteger nullable

TCP/UDP port open on the asset

Example:80

open_port_protocolstring nullable

IP protocol (tcp/udp) of an open port

open_port_servicestring nullable

Service protocol detected on an open port

open_port_technologystring nullable

Technology product identified on an open port

Example:nginx

technology_namestring nullable

Technology product identified on the asset

Example:nginx

web_technology_namestring nullable

Web technology detected via Wappalyzer

Example:jQuery

certificate_issuerstring nullable

Issuer common name of the TLS certificate

certificate_expires_beforestring date nullable

Expiration date of the TLS certificate Use this to find potentially expired certificates.

certificate_expires_afterstring date nullable

Expiration date of the TLS certificate use this to find certificates that likely haven't expired yet.

certificate_issued_beforestring date nullable

Issuance date of the TLS certificate

certificate_issued_afterstring date nullable

Issuance date of the TLS certificate

certificate_subjectstring nullable

Subject entity (common name, organization, country) of the TLS certificate

certificate_subject_alt_namestring nullable

DNS and IP subject alternative names on the TLS certificate

certificate_sha256string nullable

SHA256 fingerprint of the TLS certificate's public key

certificate_covers_domainstring nullable

Filter where the certificate's subject common name domain or one of the Subject Alternate Names exactly matches or is a wildcard covering the provided value

waf_detectedboolean nullable

Whether a Web Application Firewall was detected

waf_namestring nullable

Name of the detected Web Application Firewall

Example:Cloudflare

is_responsiveboolean nullable

Whether the asset responds to ICMP or has open ports

exposure_score_gteinteger nullable

A calculated score between 0-100 of the potential risk of the asset

exposure_score_lteinteger nullable

A calculated score between 0-100 of the potential risk of the asset

exposure_severity'informational' | 'moderate' | 'critical'

Severity level of exposures found on the asset

exposure_idstring nullable

Exposure with this signature ID found on the asset

Example:cve-2024-6387

additional_fieldsstring[] nullable

A list of additional fields to include in the response. You may specify this field multiple times or pass a comma-separated list from: custom_tags, dns_records, whois, ip_metadata, open_tcp_ports, open_udp_ports, web_technologies, certificates, certificate_chain, defenses, exposures, exposure_instance_details. By default custom_tags will be returned.

cursorstring nullable

Base 64 string for pagination included in meta.pagination.next_cursor field in previous response. If provided, will return the next page of results

Response

Successful Response

Changes

No recorded changes to this operation across all 1 revision of this API.