--- title: "Find Assets" method: GET path: "/projects/{project_id}/assets" tags: ["Assets"] --- # Find Assets `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` 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. ## Path parameters - `project_id` string, required: The ID of the project ## Query parameters - `limit` integer: The number of assets to return - `sort_by` 'discovered_at' | 'added_to_project_at' | 'last_scanned_at' | 'exposure_score' | 'asset_id' | 'apex_domain' - `sort_direction` 'asc' | 'desc' - `asset_type` string: The type of asset (ip or domain/host) - `custom_tags` string, nullable: User-defined tags on the asset - `custom_tags_strict` string, nullable: User-defined tags on the asset, matched by exact (case-sensitive) title - `has_custom_tags` boolean, nullable: Filter for assets that have at least one custom tag applied. Overrides any other custom tag filtering specified. - `added_to_project_before` string, 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_after` string, 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_before` string, 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_after` string, 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. - `apex` string, nullable: The apex domain of the assets. Only makes sense for `domain` asset types. - `referenced_ip` string, 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_before` string, 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_after` string, 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_type` string, nullable: The type of DNS record, e.g. `A`, `AAAA` or `CNAME` - `dns_resolves` boolean, 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. - `asn` integer, nullable: Autonomous System Number of the asset's IP - `cname_reference` string, 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_iso` string, nullable: ISO country code of the IP geo location - `ip_owner` string, nullable: Organization owning the IP address block - `whois_email` string, email, nullable: Email address of any current or historical WHOIS contact record, falling back to the parent domain's record - `whois_email_current` string, email, nullable: Email address of a WHOIS contact record, falling back to the parent domain's record - `open_port_number` integer, nullable: TCP/UDP port open on the asset - `open_port_protocol` string, nullable: IP protocol (tcp/udp) of an open port - `open_port_service` string, nullable: Service protocol detected on an open port - `open_port_technology` string, nullable: Technology product identified on an open port - `technology_name` string, nullable: Technology product identified on the asset - `web_technology_name` string, nullable: Web technology detected via Wappalyzer - `certificate_issuer` string, nullable: Issuer common name of the TLS certificate - `certificate_expires_before` string, date, nullable: Expiration date of the TLS certificate Use this to find potentially expired certificates. - `certificate_expires_after` string, date, nullable: Expiration date of the TLS certificate use this to find certificates that likely haven't expired yet. - `certificate_issued_before` string, date, nullable: Issuance date of the TLS certificate - `certificate_issued_after` string, date, nullable: Issuance date of the TLS certificate - `certificate_subject` string, nullable: Subject entity (common name, organization, country) of the TLS certificate - `certificate_subject_alt_name` string, nullable: DNS and IP subject alternative names on the TLS certificate - `certificate_sha256` string, nullable: SHA256 fingerprint of the TLS certificate's public key - `certificate_covers_domain` string, 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_detected` boolean, nullable: Whether a Web Application Firewall was detected - `waf_name` string, nullable: Name of the detected Web Application Firewall - `is_responsive` boolean, nullable: Whether the asset responds to ICMP or has open ports - `exposure_score_gte` integer, nullable: A calculated score between 0-100 of the potential risk of the asset - `exposure_score_lte` integer, nullable: A calculated score between 0-100 of the potential risk of the asset - `exposure_severity` 'informational' | 'moderate' | 'critical' - `exposure_id` string, nullable: Exposure with this signature ID found on the asset - `additional_fields` string[], 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. - `cursor` string, 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 `200` Successful Response - ApiListResponseAsset - `data` Asset[], required - `project_id` string, required: Project ID being displayed - `id` string, required: The asset identifier (domain or IP) - `name` string, required: The asset identifier (domain or IP). Same as `id` currently. - `type` string, required: The type of asset (ip or domain/host) - `discovered_at` string, date-time, nullable, required: 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. - `added_to_project_at` string, date-time, required: The date (Y-m-d) the asset was added to the project. This may be different than when the asset was discovered. - `last_scanned_at` string, date-time, nullable: The date (Y-m-d) when the asset was last scanned for exposures. - `apex_domain` string, nullable: The apex domain of the assets. Only makes sense for `domain` asset types. - `exposure_score` integer, nullable: A calculated score between 0-100 of the potential risk of the asset - `is_static_asset` boolean: Whether the asset is a static (always-included) asset - `custom_tags` string[], nullable: User-defined tags on the asset - `resolved_ips` string[], nullable: A convenience list of the IP addresses that A or CNAME records resolve to for this asset, or the asset itself. - `dns_records` DNSRecord[], nullable: All DNS records for the asset, keyed by record type. Read generically: any record type present is returned. - `record_type` string, required: The type of DNS record, e.g. `A`, `AAAA` or `CNAME` - `value` DNSValue[], nullable, required: A single value of a DNS record, in the shape its record type resolves to - `value` union, required: A single value of a DNS record, in the shape its record type resolves to - string - object - `seen_from` string[] - `first_seen_at` string, date-time, nullable: When the DNS record value was first resolved for the asset - `last_resolved_at` string, date-time, nullable, required: Timestamp of the last DNS resolution, applied to all record values - `is_virtual` boolean: Is this a virtual DNS record, derived from a CNAME target rather than resolved directly? - `whois` WHOISRecord - `registrar` string, nullable: Registrar name from WHOIS data, falling back to the parent domain's record - `expires_at` string, date-time, nullable: Domain expiration date from WHOIS data - `updated_at` string, date-time, nullable: Domain record last-updated date from WHOIS data - `created_at` string, date-time, nullable: Domain registration creation date from WHOIS data - `is_private` boolean, nullable: Whether the domain uses private or proxy registration - `is_from_parent` boolean: Is this WHOIS record from the parent domain? - `contacts` WHOISContact[], nullable: Current contact email, name, and organization from WHOIS data - `email` string, nullable: Email address of a WHOIS contact record, falling back to the parent domain's record - `name` string, nullable: Name of a WHOIS contact record, falling back to the parent domain's record - `organization` string, nullable: Organization of a WHOIS contact record, falling back to the parent domain's record - `is_current` boolean: Is this still a current contact? - `name_servers` string[], nullable: Name servers from WHOIS data, falling back to the parent domain's record - `certificates` CertificateInstance[], nullable: The unique certificates found on this asset (when requested). Includes ports and IPs when available. This information will also be contained in `scanned_ips` when requested - `certificate` Certificate, required - `expires_at` string, date-time, required: Expiration date of the TLS certificate - `issued_at` string, date-time, required: Issuance date of the TLS certificate - `sha256` string, required: SHA256 fingerprint of the TLS certificate's public key - `subject` CertificateEntity, required - `common_name` string, nullable: Common name (CN) of the TLS certificate's subject entity; see `certificate_issuer` for the issuer's common name / Issuer common name of the TLS certificate - `organization_name` string, nullable: Organization name of the TLS certificate's subject entity / Organization name of the TLS certificate's issuer entity - `organizational_unit_name` string, nullable: Organizational unit name of the TLS certificate's subject entity / Organizational unit name of the TLS certificate's issuer entity - `country_name` string, nullable: Country name of the TLS certificate's subject entity / Country name of the TLS certificate's issuer entity - `subject_alt_names` string[], nullable: DNS and IP subject alternative names on the TLS certificate - `issuer` CertificateEntity - `common_name` string, nullable: Common name (CN) of the TLS certificate's subject entity; see `certificate_issuer` for the issuer's common name / Issuer common name of the TLS certificate - `organization_name` string, nullable: Organization name of the TLS certificate's subject entity / Organization name of the TLS certificate's issuer entity - `organizational_unit_name` string, nullable: Organizational unit name of the TLS certificate's subject entity / Organizational unit name of the TLS certificate's issuer entity - `country_name` string, nullable: Country name of the TLS certificate's subject entity / Country name of the TLS certificate's issuer entity - `chain` Certificate[], nullable: Chain of parent certificates up to the root, in issuance order - `signature_algorithm` string, nullable: Signature algorithm used to sign the TLS certificate - `seen_ports` Port[], nullable: When available, indicates 'where' we saw this certificate. An asset may have serviced different certificates on different ports, at different times - `port` integer, required: TCP/UDP port open on the asset - `protocol` string, required: IP protocol (tcp/udp) of an open port - `instances` PortInstance[]: The specific instances of this port on an IP - `seen_ip` string, ipvanyaddress, required: IP address of each scanned host - `seen_at` string, date-time, required: Timestamp of the last scan for each scanned host - `service` string, nullable: Service protocol detected on an open port - `technology` TechnologyWithInstances - `name` string, required: Technology product identified on the asset - `vendor` string, nullable: Vendor or manufacturer of the detected Web Application Firewall - `technology_type` string, nullable: Category of a web technology or defensive measure detected via Wappalyzer (e.g. CMS, WAF, CDN) - `version` string, nullable: Version of a web technology detected via Wappalyzer - `instances` TechnologyInstance[]: Specific instances of this technology - … - `web_technologies` TechnologyWithInstances[], nullable: Web technologies detected on this port - `name` string, required: Technology product identified on the asset - `vendor` string, nullable: Vendor or manufacturer of the detected Web Application Firewall - `technology_type` string, nullable: Category of a web technology or defensive measure detected via Wappalyzer (e.g. CMS, WAF, CDN) - `version` string, nullable: Version of a web technology detected via Wappalyzer - `instances` TechnologyInstance[]: Specific instances of this technology - … - `exposures` Exposure[], nullable: Exposures detected on this port - `id` string, required: Exposure with this signature ID found on the asset - `detection_id` string, nullable, required: Exposure with this signature ID found on the asset, as raw-reported before normalization - `severity` 'informational' | 'moderate' | 'critical', required - `instances` ExposureInstance[], required: List of exposure instances on the asset - … - `details` object, nullable: Per-instance context payload used to populate exposure details - `supports_evidence` boolean, nullable: Does this exposure support evidence downloads? - `evidence_identifiers` string[], nullable: Evidence identifiers artifacts captured for this exposure - `defenses` TechnologyWithInstances[], nullable: Defensive measures in place for the port - `name` string, required: Technology product identified on the asset - `vendor` string, nullable: Vendor or manufacturer of the detected Web Application Firewall - `technology_type` string, nullable: Category of a web technology or defensive measure detected via Wappalyzer (e.g. CMS, WAF, CDN) - `version` string, nullable: Version of a web technology detected via Wappalyzer - `instances` TechnologyInstance[]: Specific instances of this technology - … - `certificate` Certificate - `expires_at` string, date-time, required: Expiration date of the TLS certificate - `issued_at` string, date-time, required: Issuance date of the TLS certificate - `sha256` string, required: SHA256 fingerprint of the TLS certificate's public key - `subject` CertificateEntity, required - `common_name` string, nullable: Common name (CN) of the TLS certificate's subject entity; see `certificate_issuer` for the issuer's common name / Issuer common name of the TLS certificate - `organization_name` string, nullable: Organization name of the TLS certificate's subject entity / Organization name of the TLS certificate's issuer entity - `organizational_unit_name` string, nullable: Organizational unit name of the TLS certificate's subject entity / Organizational unit name of the TLS certificate's issuer entity - `country_name` string, nullable: Country name of the TLS certificate's subject entity / Country name of the TLS certificate's issuer entity - `subject_alt_names` string[], nullable: DNS and IP subject alternative names on the TLS certificate - `issuer` CertificateEntity - `common_name` string, nullable: Common name (CN) of the TLS certificate's subject entity; see `certificate_issuer` for the issuer's common name / Issuer common name of the TLS certificate - `organization_name` string, nullable: Organization name of the TLS certificate's subject entity / Organization name of the TLS certificate's issuer entity - `organizational_unit_name` string, nullable: Organizational unit name of the TLS certificate's subject entity / Organizational unit name of the TLS certificate's issuer entity - `country_name` string, nullable: Country name of the TLS certificate's subject entity / Country name of the TLS certificate's issuer entity - `chain` Certificate[], nullable: Chain of parent certificates up to the root, in issuance order - `signature_algorithm` string, nullable: Signature algorithm used to sign the TLS certificate - `defenses` TechnologyWithInstances[], nullable: Defensive measures in place for the asset - `name` string, required: Technology product identified on the asset - `vendor` string, nullable: Vendor or manufacturer of the detected Web Application Firewall - `technology_type` string, nullable: Category of a web technology or defensive measure detected via Wappalyzer (e.g. CMS, WAF, CDN) - `version` string, nullable: Version of a web technology detected via Wappalyzer - `instances` TechnologyInstance[]: Specific instances of this technology - `seen_at` string, date-time, required: Timestamp of each web scan result - `seen_port` integer, required: Port number of a web scan result's URI - `seen_url` string, nullable: The URL where this technology was seen, if applicable - `exposures` Exposure[], nullable: Exposures found on this asset. Some information will overlap with that contained within `scanned_ips` - `id` string, required: Exposure with this signature ID found on the asset - `detection_id` string, nullable, required: Exposure with this signature ID found on the asset, as raw-reported before normalization - `severity` 'informational' | 'moderate' | 'critical', required - `instances` ExposureInstance[], required: List of exposure instances on the asset - `port_number` integer, required - `evidence_identifiers` string[], nullable - `details` object, nullable: Per-instance context payload used to populate exposure details - `supports_evidence` boolean, nullable: Does this exposure support evidence downloads? - `evidence_identifiers` string[], nullable: Evidence identifiers artifacts captured for this exposure - `scanned_ips` ScannedIP[], nullable: IP addresses that have been scanned for this asset - `ip` string, ipvanyaddress, required: The scanned IP address, whether the asset's own address or one it currently resolves to - `last_scanned_at` string, date-time, nullable: Timestamp of the last scan for each scanned host - `open_ports` Port[], nullable: Ports found open on this IP address - `port` integer, required: TCP/UDP port open on the asset - `protocol` string, required: IP protocol (tcp/udp) of an open port - `instances` PortInstance[]: The specific instances of this port on an IP - `seen_ip` string, ipvanyaddress, required: IP address of each scanned host - `seen_at` string, date-time, required: Timestamp of the last scan for each scanned host - `service` string, nullable: Service protocol detected on an open port - `technology` TechnologyWithInstances - `name` string, required: Technology product identified on the asset - `vendor` string, nullable: Vendor or manufacturer of the detected Web Application Firewall - `technology_type` string, nullable: Category of a web technology or defensive measure detected via Wappalyzer (e.g. CMS, WAF, CDN) - `version` string, nullable: Version of a web technology detected via Wappalyzer - `instances` TechnologyInstance[]: Specific instances of this technology - … - `web_technologies` TechnologyWithInstances[], nullable: Web technologies detected on this port - `name` string, required: Technology product identified on the asset - `vendor` string, nullable: Vendor or manufacturer of the detected Web Application Firewall - `technology_type` string, nullable: Category of a web technology or defensive measure detected via Wappalyzer (e.g. CMS, WAF, CDN) - `version` string, nullable: Version of a web technology detected via Wappalyzer - `instances` TechnologyInstance[]: Specific instances of this technology - … - `exposures` Exposure[], nullable: Exposures detected on this port - `id` string, required: Exposure with this signature ID found on the asset - `detection_id` string, nullable, required: Exposure with this signature ID found on the asset, as raw-reported before normalization - `severity` 'informational' | 'moderate' | 'critical', required - `instances` ExposureInstance[], required: List of exposure instances on the asset - … - `details` object, nullable: Per-instance context payload used to populate exposure details - `supports_evidence` boolean, nullable: Does this exposure support evidence downloads? - `evidence_identifiers` string[], nullable: Evidence identifiers artifacts captured for this exposure - `defenses` TechnologyWithInstances[], nullable: Defensive measures in place for the port - `name` string, required: Technology product identified on the asset - `vendor` string, nullable: Vendor or manufacturer of the detected Web Application Firewall - `technology_type` string, nullable: Category of a web technology or defensive measure detected via Wappalyzer (e.g. CMS, WAF, CDN) - `version` string, nullable: Version of a web technology detected via Wappalyzer - `instances` TechnologyInstance[]: Specific instances of this technology - … - `certificate` Certificate - `expires_at` string, date-time, required: Expiration date of the TLS certificate - `issued_at` string, date-time, required: Issuance date of the TLS certificate - `sha256` string, required: SHA256 fingerprint of the TLS certificate's public key - `subject` CertificateEntity, required - `common_name` string, nullable: Common name (CN) of the TLS certificate's subject entity; see `certificate_issuer` for the issuer's common name / Issuer common name of the TLS certificate - `organization_name` string, nullable: Organization name of the TLS certificate's subject entity / Organization name of the TLS certificate's issuer entity - `organizational_unit_name` string, nullable: Organizational unit name of the TLS certificate's subject entity / Organizational unit name of the TLS certificate's issuer entity - `country_name` string, nullable: Country name of the TLS certificate's subject entity / Country name of the TLS certificate's issuer entity - `subject_alt_names` string[], nullable: DNS and IP subject alternative names on the TLS certificate - `issuer` CertificateEntity - `common_name` string, nullable: Common name (CN) of the TLS certificate's subject entity; see `certificate_issuer` for the issuer's common name / Issuer common name of the TLS certificate - `organization_name` string, nullable: Organization name of the TLS certificate's subject entity / Organization name of the TLS certificate's issuer entity - `organizational_unit_name` string, nullable: Organizational unit name of the TLS certificate's subject entity / Organizational unit name of the TLS certificate's issuer entity - `country_name` string, nullable: Country name of the TLS certificate's subject entity / Country name of the TLS certificate's issuer entity - `chain` Certificate[], nullable: Chain of parent certificates up to the root, in issuance order - `signature_algorithm` string, nullable: Signature algorithm used to sign the TLS certificate - `metadata` IPMetadata - `as_number` integer, nullable: Autonomous System Number of the asset's IP - `owner_name` string, nullable: Organization owning the IP address block - `registry` string, nullable: Regional internet registry source for the IP - `owner_geo` GeoLocation - `continent` string, nullable: Continent name of the IP address' owner geolocation - `country` string, nullable: Country name of the IP address' owner geolocation - `city` string, nullable: City name of the IP address' owner geolocation - `country_iso` string, nullable: ISO country code of the IP geo location - `is_responsive` boolean, nullable: Whether the asset responds to ICMP or has open ports - `meta` ApiMeta, required - `params` object, nullable - `counts` ApiCount - `total` integer, nullable - `returned` integer, required - `pagination` PaginationResponse - `next_cursor` string, nullable: An opaque value which should be passed as the `cursor` to retrieve the nextpage of results - `limit` integer, nullable: The number of items returned - `total` integer, nullable - `sort` array[], nullable: The sort order of the results - unknown[] - unknown - `request_id` string, nullable ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/recordedfuture/apis/attack-surface-intelligence.md) - [All operations](https://skmtc.dev/recordedfuture/apis/attack-surface-intelligence/llms.txt) - [OpenAPI document](https://skmtc.dev/recordedfuture/apis/attack-surface-intelligence/revisions/7fd5c7304957?raw)