---
updatedAt: 2026-03-21T04:09:25.000Z
agentTools:
  projectIndex: https://docs.recordedfuture.com/llms.txt
---

# ASI Assets: Get Filters

Discover available filter facets and their values across all project assets.

### What this endpoint does

Retrieve the available filter facets for a project's assets, including the distinct values for each filter field and the number of assets matching each value. This is a discovery endpoint — use it to understand what filter criteria are available before constructing queries with the Find Assets or Search Assets endpoints. By default, it returns facets for asset type, custom tags, IP owner, exposure severity, open port numbers, and certificate expiration; use the `filter_fields` query parameter to request specific facets from the full set of 24 available fields covering asset identity, network infrastructure, certificates, exposures, and technologies.

### Response data

Returns filter facets organized by property group (asset, certificate, exposure, technology). Each facet includes a human-readable name, the query parameter name for the Find Assets endpoint, the dotted JSON path for constructing Search Assets POST filters, the operator type (eq, in, or date\_range), and an array of available values with their asset counts. Date-range facets include pre-computed time windows (e.g., "Last 30 days", "Next 90 days") with start and end dates.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "ASI Project API",
    "description": "\nThe Attack Surface Intelligence (ASI) Project API is designed to allow you full-featured access\nto all of the `Assets` within all of the `Project`s as well as , most importantly, the `Exposures` that our\nsystem has identified on those assets, including proposed remediations.\n\nYou can create new user-defined `Tags` and apply them to `Assets` either individually or in bulk.\n\nYou can use either the GET-based listing endpoint to find assets or the /_search endpoint which\naccepts a more structured request and, in the future, will allow for even more complex boolean queries.\n\nUsing it only requires a standard Security Trails API access key.\n",
    "version": "v1.7.0"
  },
  "servers": [
    {
      "url": "https://api.securitytrails.com/v2",
      "description": "Security Trails API"
    }
  ],
  "paths": {
    "/projects/{project_id}/filters": {
      "get": {
        "tags": [
          "Assets"
        ],
        "summary": "Get Filters",
        "description": "Discover available filter facets and their values across all project assets.",
        "operationId": "Assets-get_filters",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Project Id"
            }
          },
          {
            "name": "filter_fields",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                {
                  "type": "null"
                }
              ],
              "description": "A list of additional fields to include in the response.You may specify this field multiple times or pass a comma-separated list from: `asset_type`, `asn`, `custom_tags`, `added_to_project`, `discovered`, `apex`, `ip_geo_country_iso`, `ip_owner`, `static_asset`, `registry`, `referenced_ip`, `exposure_id`, `severity`, `asset_exposure_score`, `last_scanned_at`, `open_port_number`, `open_port_service`, `open_port_protocol`, `waf_detected`, `waf_name`, `technology_name`, `is_responsive`, `certificate_issuer`, `certificate_expires_at`, `certificate_issued_at`.By default `asset_type`, `custom_tags`, `ip_owner`, `severity`, `open_port_number`, `certificate_expires_at` is returned.If one query input is equal to all, all fields are returned.",
              "title": "Filter Fields"
            },
            "description": "A list of additional fields to include in the response.You may specify this field multiple times or pass a comma-separated list from: `asset_type`, `asn`, `custom_tags`, `added_to_project`, `discovered`, `apex`, `ip_geo_country_iso`, `ip_owner`, `static_asset`, `registry`, `referenced_ip`, `exposure_id`, `severity`, `asset_exposure_score`, `last_scanned_at`, `open_port_number`, `open_port_service`, `open_port_protocol`, `waf_detected`, `waf_name`, `technology_name`, `is_responsive`, `certificate_issuer`, `certificate_expires_at`, `certificate_issued_at`.By default `asset_type`, `custom_tags`, `ip_owner`, `severity`, `open_port_number`, `certificate_expires_at` is returned.If one query input is equal to all, all fields are returned."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FiltersResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AssetCountDateRangeFilter": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name"
          },
          "asset_count": {
            "type": "integer",
            "title": "Asset Count"
          },
          "start": {
            "anyOf": [
              {
                "type": "string",
                "format": "date"
              },
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Start"
          },
          "end": {
            "anyOf": [
              {
                "type": "string",
                "format": "date"
              },
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "End"
          }
        },
        "type": "object",
        "required": [
          "name",
          "asset_count",
          "start",
          "end"
        ],
        "title": "AssetCountDateRangeFilter",
        "description": "Date range filter with asset count context."
      },
      "AssetCountEqFilter": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name"
          },
          "asset_count": {
            "type": "integer",
            "title": "Asset Count"
          },
          "value": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ],
            "title": "Value"
          }
        },
        "type": "object",
        "required": [
          "name",
          "asset_count",
          "value"
        ],
        "title": "AssetCountEqFilter",
        "description": "Equality filter with asset count context."
      },
      "AssetCountValueRangeFilter": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name"
          },
          "asset_count": {
            "type": "integer",
            "title": "Asset Count"
          },
          "start": {
            "type": "integer",
            "title": "Start"
          },
          "end": {
            "type": "integer",
            "title": "End"
          }
        },
        "type": "object",
        "required": [
          "name",
          "asset_count",
          "start",
          "end"
        ],
        "title": "AssetCountValueRangeFilter",
        "description": "Value range filter with asset count context."
      },
      "AssetPropertiesFilterOptions": {
        "properties": {
          "asset_type": {
            "$ref": "#/components/schemas/FilterOptionsEq",
            "description": "The type of asset, one of: `ip`, `domain` and `host`(where `domain` and `host` represent the same asset type)."
          },
          "asn": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "Filter for assets which either are, or point to, an IP address announced by the provided ASN (e.g. `16509`)."
          },
          "custom_tags": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "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."
          },
          "added_to_project": {
            "$ref": "#/components/schemas/FilterOptionsDateRange",
            "description": "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": {
            "$ref": "#/components/schemas/FilterOptionsDateRange",
            "description": "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": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "Filter on the apex domain of the assets. Only makes sense for `domain` asset types. Example: `example.com`"
          },
          "static_asset": {
            "$ref": "#/components/schemas/FilterOptionsEq",
            "description": "Filter static and non static assets."
          },
          "ip_geo_country_iso": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "Filter for assets which either are, or point to, an IP address located in the provided ISO country code (e.g. `US`)."
          },
          "ip_owner": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "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."
          },
          "registry": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "Filter for assets by their IP registry source (e.g., 'arin', 'ripe', 'apnic')."
          },
          "referenced_ip": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "Filter on an A or CNAME record pointing to the IP address. Use `eq` or `in` for exact IP matching. Use `contains` with a trailing `.` for CIDR range matching, or without for prefix matching."
          }
        },
        "type": "object",
        "title": "AssetPropertiesFilterOptions",
        "description": "Available asset property filter facets with value counts."
      },
      "CertificatePropertiesFilterOptions": {
        "properties": {
          "certificate_issuer": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "Filter where the certificate (or in the chain) issuer's common name or organization matches the provided value"
          },
          "certificate_expires_at": {
            "$ref": "#/components/schemas/FilterOptionsDateRange",
            "description": "Filter where the certificate expiration matches the provided value"
          },
          "certificate_issued_at": {
            "$ref": "#/components/schemas/FilterOptionsDateRange",
            "description": "Filter where the certificate issuance date matches the provided value"
          }
        },
        "type": "object",
        "title": "CertificatePropertiesFilterOptions",
        "description": "Available certificate property filter facets with value counts."
      },
      "ExposurePropertiesFilterOptions": {
        "properties": {
          "signature_id": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "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`."
          },
          "severity": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "Filter for assets which have an exposure severity matching or higher than the provided value. Acceptable values: unknown, informational, moderate, critical."
          },
          "asset_exposure_score": {
            "$ref": "#/components/schemas/FilterOptionsValueRange",
            "description": "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."
          },
          "last_scanned_at": {
            "$ref": "#/components/schemas/FilterOptionsDateRange",
            "description": "Filter on the date (Y-m-d) when the asset was last scanned for exposures."
          }
        },
        "type": "object",
        "title": "ExposurePropertiesFilterOptions",
        "description": "Available exposure property filter facets with value counts."
      },
      "FilterOptionsDateRange": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name"
          },
          "filter_query": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Filter Query"
          },
          "filter_path": {
            "type": "string",
            "title": "Filter Path"
          },
          "filter_type": {
            "type": "string",
            "title": "Filter Type",
            "default": "date_range"
          },
          "filters": {
            "items": {
              "$ref": "#/components/schemas/AssetCountDateRangeFilter"
            },
            "type": "array",
            "title": "Filters"
          }
        },
        "type": "object",
        "required": [
          "name",
          "filter_query",
          "filter_path",
          "filters"
        ],
        "title": "FilterOptionsDateRange",
        "description": "Date range filter option with available values and counts."
      },
      "FilterOptionsEq": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name"
          },
          "filter_query": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Filter Query"
          },
          "filter_path": {
            "type": "string",
            "title": "Filter Path"
          },
          "filter_type": {
            "type": "string",
            "title": "Filter Type",
            "default": "eq"
          },
          "filters": {
            "items": {
              "$ref": "#/components/schemas/AssetCountEqFilter"
            },
            "type": "array",
            "title": "Filters"
          }
        },
        "type": "object",
        "required": [
          "name",
          "filter_query",
          "filter_path",
          "filters"
        ],
        "title": "FilterOptionsEq",
        "description": "Equality filter option with available values and counts."
      },
      "FilterOptionsIn": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name"
          },
          "filter_query": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Filter Query"
          },
          "filter_path": {
            "type": "string",
            "title": "Filter Path"
          },
          "filter_type": {
            "type": "string",
            "title": "Filter Type",
            "default": "in"
          },
          "filters": {
            "items": {
              "$ref": "#/components/schemas/AssetCountEqFilter"
            },
            "type": "array",
            "title": "Filters"
          }
        },
        "type": "object",
        "required": [
          "name",
          "filter_query",
          "filter_path",
          "filters"
        ],
        "title": "FilterOptionsIn",
        "description": "Inclusion filter option with available values and counts."
      },
      "FilterOptionsValueRange": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name"
          },
          "filter_query": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Filter Query"
          },
          "filter_path": {
            "type": "string",
            "title": "Filter Path"
          },
          "filter_type": {
            "type": "string",
            "title": "Filter Type",
            "default": "value_range"
          },
          "filters": {
            "items": {
              "$ref": "#/components/schemas/AssetCountValueRangeFilter"
            },
            "type": "array",
            "title": "Filters"
          }
        },
        "type": "object",
        "required": [
          "name",
          "filter_query",
          "filter_path",
          "filters"
        ],
        "title": "FilterOptionsValueRange",
        "description": "Value range filter option with available values and counts."
      },
      "FiltersResponse": {
        "properties": {
          "asset_properties": {
            "$ref": "#/components/schemas/AssetPropertiesFilterOptions"
          },
          "exposure_properties": {
            "$ref": "#/components/schemas/ExposurePropertiesFilterOptions"
          },
          "technology_properties": {
            "$ref": "#/components/schemas/TechnologyPropertiesFilterOptions"
          },
          "certificate_properties": {
            "$ref": "#/components/schemas/CertificatePropertiesFilterOptions"
          }
        },
        "type": "object",
        "required": [
          "asset_properties",
          "exposure_properties",
          "technology_properties",
          "certificate_properties"
        ],
        "title": "FiltersResponse",
        "description": "Available filter facets with asset counts for building search queries. Each property contains the available filter options for that category."
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError",
        "description": "Validation error response with detail about which fields failed."
      },
      "TechnologyPropertiesFilterOptions": {
        "properties": {
          "open_port_number": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "Filter for assets which have an open port with the provided number (e.g. `80`)."
          },
          "open_port_service": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "Filter for assets which have an open port that appears to support the provided protocol (e.g. `http`, `rdp`, `ftp`)."
          },
          "open_port_protocol": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "Filter for assets which have an open port on the provided protocol (e.g. `tcp`, `udp`)."
          },
          "waf_detected": {
            "$ref": "#/components/schemas/FilterOptionsEq",
            "description": "Filter for assets where a WAF (Web Application Firewall) is detected."
          },
          "waf_name": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "Filter for assets where a specific WAF is detected. Will attempt to match both vendor and product, e.g. `Cloudflare`."
          },
          "technology_name": {
            "$ref": "#/components/schemas/FilterOptionsIn",
            "description": "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')"
          },
          "is_responsive": {
            "$ref": "#/components/schemas/FilterOptionsEq",
            "description": "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."
          }
        },
        "type": "object",
        "title": "TechnologyPropertiesFilterOptions",
        "description": "Available technology property filter facets with value counts."
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError",
        "description": "Individual field validation error with location and message."
      }
    },
    "securitySchemes": {
      "APIKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "apikey"
      }
    }
  },
  "x-readme": {
    "proxy-enabled": false
  }
}
```