---
title: "Find Assets"
method: GET
path: "/projects/{project_id}/assets"
tags: ["Assets"]
---

# Find Assets

`GET /projects/{project_id}/assets`

List and filter project assets using query-parameter-based criteria with OR logic.

## Path parameters

- `project_id` string, required

## Query parameters

- `cursor` string — Opaque string provided in `next_cursor` of previous results
- `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' — Field to sort asset results by.
- `sort_direction` 'asc' | 'desc' — Sort direction (ascending or descending).
- `asset_type` string — The type of asset, one of: `ip`, `domain` and `host`(where `domain` and `host` represent the same asset type).
- `custom_tags` string — Filter by custom tags placed on your assets. `strict` version will return a validation error if any of the tags have not been defined on your project.
- `custom_tags_strict` string — Filter by custom tags placed on your assets. `strict` version will return a validation error if any of the tags have not been defined on your project.
- `has_custom_tags` boolean — Filter for assets that have at least one custom tag applied. Overrides any other custom tag filtering specified.
- `added_to_project_before` string, date — Filter on 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 — Filter on 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 — Filter on the date (Y-m-d) the asset was discovered by Recorded Future ASI. 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 — Filter on the date (Y-m-d) the asset was discovered by Recorded Future ASI. 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 — Filter on the apex domain of the assets. Only makes sense for `domain` asset types. Example: `example.com`
- `referenced_ip` string, ipvanynetwork
- `referenced_ip_before` string, date — 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 — 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 — Filter for assets that have this DNS record type, e.g. `A`,`CNAME`,`MX`.
- `dns_resolves` boolean — 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 — Filter for assets which either are, or point to, an IP address announced by the provided ASN (e.g. `16509`).
- `cname_reference` string — 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 — Filter for assets which either are, or point to, an IP address located in the provided ISO country code (e.g. `US`).
- `ip_owner` string — Filter for assets which either are, or point to, an IP address owned by the provided organization. This will often be an ISP or hosting provider or simply the name of the AS owning the IP.
- `whois_email` string, email — Filter for assets where the WHOIS email address matches the provided value. For subdomains the parent record will be partially used. The `current` variant will only return results where the email is on the current (rather than historical) versions of the WHOIS.
- `whois_email_current` string, email — Filter for assets where the WHOIS email address matches the provided value. For subdomains the parent record will be partially used. The `current` variant will only return results where the email is on the current (rather than historical) versions of the WHOIS.
- `open_port_number` integer — Filter for assets which have an open port with the provided number (e.g. `80`).
- `open_port_protocol` string — Filter for assets which have an open port on the provided protocol (e.g. `tcp`, `udp`).
- `open_port_service` string — Filter for assets which have an open port that appears to support the provided protocol (e.g. `http`, `rdp`, `ftp`).
- `open_port_technology` string — Filter for assets which have a specific product listening on an open port (e.g. `nginx`, `apache httpd`)
- `technology_name` string — Filter for the name of a technology found on the asset. Could be directly attached to the port (`nginx`, etc) or a web technology (e.g. 'jQuery', 'Wordpress')
- `web_technology_name` string — Filter for the name of a technology specifically associated with 'web' resources, such as `jQuery` or `Wordpress`). **NOTE**: In some cases where a port has been closed we may still report findings of web technologies that we previously saw on those ports.
- `certificate_issuer` string — Filter where the certificate (or in the chain) issuer's common name or organization matches the provided value
- `certificate_expires_before` string, date — Filter where the certificate expiration matches the provided value Use this to find potentially expired certificates.
- `certificate_expires_after` string, date — Filter where the certificate expiration matches the provided value use this to find certificates that likely haven't expired yet.
- `certificate_issued_before` string, date — Filter where the certificate issuance date matches the provided value
- `certificate_issued_after` string, date — Filter where the certificate issuance date matches the provided value
- `certificate_subject` string — Filter where certificate `subject` or `organizationName` matches the provided value
- `certificate_subject_alt_name` string — Filter here the certificate Subject Alternate Names section matches the provided value
- `certificate_sha256` string — Filter where the certificate public key sha256 value matches the provided value
- `certificate_covers_domain` string — 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 — Filter for assets where a WAF (Web Application Firewall) is detected.
- `waf_name` string — Filter for assets where a specific WAF is detected. Will attempt to match both vendor and product, e.g. `Cloudflare`.
- `is_responsive` boolean — Filter for assets that are unresponsive over ICMP and no ports are open. This is a boolean filter, so it will return assets that are either responsive or not responsive.
- `exposure_score_gte` integer — Filter for assets which have an exposure score within the provided range. This is a score from 0-100 that indicates the potential risk of the asset based on various factors. You may specify only one 'end' based on your needs.
- `exposure_score_lte` integer — Filter for assets which have an exposure score within the provided range. This is a score from 0-100 that indicates the potential risk of the asset based on various factors. You may specify only one 'end' based on your needs.
- `exposure_severity` 'unknown' | 'informational' | 'moderate' | 'critical' — Exposure severity level.
- `exposure_id` string — Filter for assets which have an exposure with the provided ASI Signature ID. Note that some signatures line up with CVEs, but this should not be relied upon. Examples: `cve-2024-6387`, `cve-OpenSSH`.
- `additional_fields` string[] — A list of additional fields to include in the response from the following. 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 the custom tags will be returned.

## Response `200`

Successful Response

- ApiListResponseAsset — Paginated list of assets in a project.
  - `data` Asset[], required
    - `project_id` string, required — Project ID being displayed
    - `id` string, required — The asset identifier. Same as `name` currently. In the future this may become a more opaque value.
    - `name` string, required — The asset identifier. Same as `id` currently.
    - `type` string, required — Indicates the type of assets. Currently will be one of `domain` or `ip
    - `discovered_at` string, date-time, nullable, required — Indicates when Recorded Future ASI first identified this asset on the Internet. For IP assets this is a fixed value
    - `added_to_project_at` string, date-time, required — Indicates when this asset became part of your project, which may be when it was first discovered or when a rule allowed it in
    - `last_scanned_at` string, date-time, nullable — Indicates the last occurrence of some scanning activity on this asset, which could be port or vulnerability scans. On-Demand scans will 'bump' this date.
    - `apex_domain` string, nullable — For `domain` assets, the 'top' domain this is a part of. E.g. for `foo.bar.example.com` this would be `example.com`
    - `exposure_score` integer, nullable — The Recorded Future ASI-calculated score based on the Exposures found on your asset.
    - `is_static_asset` boolean — Indicates whether this asset was discovered as part of project rules (`false`) or was added manually (`true`).
    - `custom_tags` string[], nullable — User-defined tags which have been put on this asset. **NOTE**: After calling tagging endpoints, there may be a delay of up to a couple minutes before tags appear.
    - `resolved_ips` string[], nullable — A convenience list of the IP addresses that A or CNAME records resolve to for this asset, or the aset iself.
    - `dns_records` DNSRecord[], nullable — List of DNS records we have queried with
      - `record_type` string, required
      - `value` DNSValue[], nullable, required
        - `value` union, required
          - string
          - object
        - `seen_from` string[]
        - `first_seen_at` string, date-time, nullable
        - `last_resolved_at` string, date-time, nullable, required
      - `is_virtual` boolean — Is this a virtual DNS record?
    - `whois` WHOISRecord — From proposal: contact.email contact.organization contact.name expires created updated registrar
      - `registrar` string, nullable — Registrar of the domain if known
      - `expires_at` string, date-time, nullable — Expiration date of the domain
      - `updated_at` string, date-time, nullable — Last updated date of the domain
      - `created_at` string, date-time, nullable — Creation date of the domain
      - `is_private` boolean, nullable — Is the domain registration private?
      - `is_from_parent` boolean — Is this WHOIS record from the parent domain?
      - `contacts` WHOISContact[], nullable — Contacts associated with the domain
        - `email` string, nullable — Email address of the contact
        - `name` string, nullable — Name of the contact, if available
        - `organization` string, nullable — Organization of the contact
        - `is_current` boolean — Is this still a current contact?
      - `name_servers` string[], nullable — Primary nameservers for the domain
    - `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 — TLS/SSL certificate details found on an asset.
        - `expires_at` string, date-time, required
        - `issued_at` string, date-time, required
        - `sha256` string, required
        - `subject` CertificateEntity, required — Certificate entity (subject or issuer) with organization details.
          - `common_name` string, nullable
          - `organization_name` string, nullable
          - `organizational_unit_name` string, nullable
          - `country_name` string, nullable
        - `subject_alt_names` string[], nullable
        - `issuer` CertificateEntity — Certificate entity (subject or issuer) with organization details.
          - `common_name` string, nullable
          - `organization_name` string, nullable
          - `organizational_unit_name` string, nullable
          - `country_name` string, nullable
        - `chain` Certificate[], nullable
        - `signature_algorithm` string, nullable
      - `seen_ports` Port[], nullable — When available, indicates 'where' we saw this certificate. An asset may have serviced different certificaes on different ports, at different times
        - `port` integer, required — The open port number
        - `protocol` string, required — The protocol of the open port, should be one of UDP or TCP
        - `instances` PortInstance[] — The specific instances of this port on an IP
          - `seen_ip` union, required
            - string, ipvanyaddress
            - string, ipv6
          - `seen_at` string, date-time, required
          - `service` string, nullable — The service protocol running on the open port
          - `technology` TechnologyWithInstances — A technology with all instances where it was detected.
            - `name` string, required — The name of the technology, sometimes prefixed with the vendor
            - `vendor` string, nullable — If available, the vendor of the product
            - `technology_type` string, nullable — If available, the type of technology
            - `version` string, nullable — If available, the specific version of the product
            - `instances` TechnologyInstance[] — Specific instances of this technology
              - …
          - `web_technologies` TechnologyWithInstances[], nullable — Web technologies detected on this port
            - `name` string, required — The name of the technology, sometimes prefixed with the vendor
            - `vendor` string, nullable — If available, the vendor of the product
            - `technology_type` string, nullable — If available, the type of technology
            - `version` string, nullable — If available, the specific version of the product
            - `instances` TechnologyInstance[] — Specific instances of this technology
              - …
          - `exposures` Exposure[], nullable — Exposures detected on this port
            - `id` string, required
            - `detection_id` string, nullable, required
            - `severity` 'unknown' | 'informational' | 'moderate' | 'critical', required — Exposure severity level.
            - `instances` ExposureInstance[], required
              - …
            - `details` object, nullable
            - `supports_evidence` boolean, nullable — Does this exposure support evidence downloads?
          - `defenses` DefensiveControl[], nullable — Defensive measures in place for the port
            - `name` string, required — The name of the technology, sometimes prefixed with the vendor
            - `vendor` string, nullable — If available, the vendor of the product
            - `technology_type` string, nullable — If available, the type of technology
            - `version` string, nullable — If available, the specific version of the product
            - `instances` TechnologyInstance[] — Specific instances of this technology
              - …
        - `certificate` Certificate — TLS/SSL certificate details found on an asset.
          - `expires_at` string, date-time, required
          - `issued_at` string, date-time, required
          - `sha256` string, required
          - `subject` CertificateEntity, required — Certificate entity (subject or issuer) with organization details.
            - `common_name` string, nullable
            - `organization_name` string, nullable
            - `organizational_unit_name` string, nullable
            - `country_name` string, nullable
          - `subject_alt_names` string[], nullable
          - `issuer` CertificateEntity — Certificate entity (subject or issuer) with organization details.
            - `common_name` string, nullable
            - `organization_name` string, nullable
            - `organizational_unit_name` string, nullable
            - `country_name` string, nullable
          - `chain` Certificate[], nullable
          - `signature_algorithm` string, nullable
    - `defenses` DefensiveControl[], nullable — Defensive measures in place for the asset
      - `name` string, required — The name of the technology, sometimes prefixed with the vendor
      - `vendor` string, nullable — If available, the vendor of the product
      - `technology_type` string, nullable — If available, the type of technology
      - `version` string, nullable — If available, the specific version of the product
      - `instances` TechnologyInstance[] — Specific instances of this technology
        - `seen_at` string, date-time, required
        - `seen_port` integer, required
        - `seen_url` string, uri, nullable — The URL where this technology was seen, if applicable
    - `exposures` Exposure[], nullable — Exposures found on this asset. Some information will overlap with tah contained within `scanned_ips`
      - `id` string, required
      - `detection_id` string, nullable, required
      - `severity` 'unknown' | 'informational' | 'moderate' | 'critical', required — Exposure severity level.
      - `instances` ExposureInstance[], required
        - `port_number` integer, required
        - `url` string, nullable
        - `details` object, nullable
      - `details` object, nullable
      - `supports_evidence` boolean, nullable — Does this exposure support evidence downloads?
    - `scanned_ips` ScannedIP[], nullable — IP addresses that have been scanned for this asset
      - `ip` string, ipvanyaddress, required
      - `last_scanned_at` string, date-time, nullable — Datetime when a port scan was run on this IP address
      - `whois` WHOISRecord — From proposal: contact.email contact.organization contact.name expires created updated registrar
        - `registrar` string, nullable — Registrar of the domain if known
        - `expires_at` string, date-time, nullable — Expiration date of the domain
        - `updated_at` string, date-time, nullable — Last updated date of the domain
        - `created_at` string, date-time, nullable — Creation date of the domain
        - `is_private` boolean, nullable — Is the domain registration private?
        - `is_from_parent` boolean — Is this WHOIS record from the parent domain?
        - `contacts` WHOISContact[], nullable — Contacts associated with the domain
          - `email` string, nullable — Email address of the contact
          - `name` string, nullable — Name of the contact, if available
          - `organization` string, nullable — Organization of the contact
          - `is_current` boolean — Is this still a current contact?
        - `name_servers` string[], nullable — Primary nameservers for the domain
      - `open_ports` Port[], nullable
        - `port` integer, required — The open port number
        - `protocol` string, required — The protocol of the open port, should be one of UDP or TCP
        - `instances` PortInstance[] — The specific instances of this port on an IP
          - `seen_ip` union, required
            - string, ipvanyaddress
            - string, ipv6
          - `seen_at` string, date-time, required
          - `service` string, nullable — The service protocol running on the open port
          - `technology` TechnologyWithInstances — A technology with all instances where it was detected.
            - `name` string, required — The name of the technology, sometimes prefixed with the vendor
            - `vendor` string, nullable — If available, the vendor of the product
            - `technology_type` string, nullable — If available, the type of technology
            - `version` string, nullable — If available, the specific version of the product
            - `instances` TechnologyInstance[] — Specific instances of this technology
              - …
          - `web_technologies` TechnologyWithInstances[], nullable — Web technologies detected on this port
            - `name` string, required — The name of the technology, sometimes prefixed with the vendor
            - `vendor` string, nullable — If available, the vendor of the product
            - `technology_type` string, nullable — If available, the type of technology
            - `version` string, nullable — If available, the specific version of the product
            - `instances` TechnologyInstance[] — Specific instances of this technology
              - …
          - `exposures` Exposure[], nullable — Exposures detected on this port
            - `id` string, required
            - `detection_id` string, nullable, required
            - `severity` 'unknown' | 'informational' | 'moderate' | 'critical', required — Exposure severity level.
            - `instances` ExposureInstance[], required
              - …
            - `details` object, nullable
            - `supports_evidence` boolean, nullable — Does this exposure support evidence downloads?
          - `defenses` DefensiveControl[], nullable — Defensive measures in place for the port
            - `name` string, required — The name of the technology, sometimes prefixed with the vendor
            - `vendor` string, nullable — If available, the vendor of the product
            - `technology_type` string, nullable — If available, the type of technology
            - `version` string, nullable — If available, the specific version of the product
            - `instances` TechnologyInstance[] — Specific instances of this technology
              - …
        - `certificate` Certificate — TLS/SSL certificate details found on an asset.
          - `expires_at` string, date-time, required
          - `issued_at` string, date-time, required
          - `sha256` string, required
          - `subject` CertificateEntity, required — Certificate entity (subject or issuer) with organization details.
            - `common_name` string, nullable
            - `organization_name` string, nullable
            - `organizational_unit_name` string, nullable
            - `country_name` string, nullable
          - `subject_alt_names` string[], nullable
          - `issuer` CertificateEntity — Certificate entity (subject or issuer) with organization details.
            - `common_name` string, nullable
            - `organization_name` string, nullable
            - `organizational_unit_name` string, nullable
            - `country_name` string, nullable
          - `chain` Certificate[], nullable
          - `signature_algorithm` string, nullable
      - `metadata` IPMetadata — Metadata about an IP address including ASN and geolocation.
        - `as_number` integer, nullable — Autonomous System Number which IP/block is registered to
        - `owner_name` string, nullable — AS or Org Name of the IP/block is registered to
        - `registry` string, nullable — Nearest or top-level RIR
        - `owner_geo` GeoLocation — Geographic location data for an IP address.
          - `continent` string, nullable — Continent of the IP address
          - `country` string, nullable — Country of the IP address
          - `city` string, nullable — City of the IP address
          - `country_iso` string, nullable — ISO code of the country of the IP address
      - `is_responsive` boolean, nullable — Indicates whether this IP address is unresponsive over ICMP and no ports were found open
  - `meta` ApiMeta, required — Response metadata including pagination, counts, and request parameters.
    - `params` object, nullable
    - `counts` ApiCount — Result count metadata.
      - `total` integer, nullable
      - `returned` integer, required
    - `pagination` PaginationResponse — Cursor-based pagination data in responses.
      - `next_cursor` string, nullable — An opaque value which should be passed as the `cursor` to retrieve the next page of results. If None or not present there are no remaining pages. This value should not be interpreted by the client.
      - `limit` integer — 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.net/recordedfuture/apis/alert-api.md) · [All operations](https://skmtc.net/recordedfuture/apis/alert-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/recordedfuture/alert-api/revisions/c8c2f68d8b60/schema)