Filtering

Refine TAXII results using query string filter parameters.

Filter STIX objects in your TAXII requests to retrieve exactly the data you need. All filters are query string parameters and can be combined for precise control.

Available Filters

The filters you can use include both those required by the TAXII specification and additional filters specific to Pulsedive.

Standard TAXII Filters

These filters are required by the TAXII specification:

Filter	Type	Description	Example
limit	Positive integer	Number of objects to return in response. Default varies by collection. Pulsedive has a maximum server limit of 1000.	100
next	String	Pagination token from previous response. To learn more about pagination, visit Pagination.	2024-01-15%2010:30:45|12345
added_after	Timestamp	Filter by STIX objects added after the specified date and time. Supports STIX timestamps (YYYY-MM-DDTHH:MM:SS.MMMZ) and Pulsedive format (YYYY-MM-DD HH:MM:SS).	2024-01-15T11:45:30.000Z
match[id]	String	Filter by specific STIX object ID(s). Supports comma-separated list.	indicator--12345678-1234-5678-9012-123456789012
match[spec_version]	String	Filter by STIX specification version(s). Supports comma-separated list.	2.1
match[type]	String	Filter by STIX object type(s). Supports comma-separated list. For STIX Domain Objects, visit the STIX specification.	indicator
match[version]	String	Filter by STIX object version(s). Supports comma-separated list. Options include: first, last, all, timestamps in either STIX (YYYY-MM-DDTHH:MM:SS.MMMZ) or Pulsedive (YYYY-MM-DD HH:MM:SS) format. Pulsedive doesn’t have object versions, so the first, last, and all keywords will all return the latest object version.	first 2024-01-15T11:45:30.000Z 2024-01-15 11:24:30

Pulsedive-Specific Filters

Pulsedive provides these additional filters:

Filter	Type	Description	Example
match[seen]	Timestamp	Filter by last seen timestamp(s). Supports comma-separated list. Supports STIX-spec timestamps (YYYY-MM-DDTHH:MM:SS.MMMZ) and Pulsedive’s timestamp format (YYYY-MM-DD HH:MM:SS)	2024-01-15T11:45:30.000Z 2024-01-15 11:24:30
match[risk]	String	Filter by risk score. Options: unknown, none, very low, low, medium, high, critical. Supports comma-separated list.	low
match[itype]	String	Filter by indicator type(s). Options include: ip, ipv6, domain, url. Supports comma-separated list.	ip
match[retired]	Boolean	Filter by retired (true) or active (false) indicators.	true

Filter Examples

These are some sample requests.

Sample requests won’t work without a valid API key. Get one by signing up for a free account.

Use collection ID 981c4916-ebb2-4567-aece-54ae970c4230 (test collection) for safe experimentation.

Basic Filtering

# Get high-risk domains from the last 30 days
curl "https://pulsedive.com/taxii2/api/collections/a5cffbfe-c0ff-4842-a235-cb3a7a040a37/objects/ \
    ?key=<YOUR_API_KEY> \
    &accept=application/taxii+json;version=2.1 \
    &match[risk]=high \
    &match[itype]=domain \
    &limit=100 \
    &pretty=1"

Multiple Risk Levels

# Get high and critical risk indicators
curl "https://pulsedive.com/taxii2/api/collections/a5cffbfe-c0ff-4842-a235-cb3a7a040a37/objects/ \
    ?key=<YOUR_API_KEY> \
    &accept=application/taxii+json;version=2.1 \
    &match[risk]=high,critical \
    &limit=50 \
    &pretty=1"

Time-Based Filtering

# Get indicators added after January 1, 2024
curl "https://pulsedive.com/taxii2/api/collections/a5cffbfe-c0ff-4842-a235-cb3a7a040a37/objects/ \
    ?key=<YOUR_API_KEY> \
    &accept=application/taxii+json;version=2.1 \
    &added_after=2024-01-01T00:00:00.000Z \
    &pretty=1"

Active vs Retired Indicators

# Get only active (non-retired) indicators
curl "https://pulsedive.com/taxii2/api/collections/a5cffbfe-c0ff-4842-a235-cb3a7a040a37/objects/ \
    ?key=<YOUR_API_KEY> \
    &accept=application/taxii+json;version=2.1 \
    &match[retired]=false \
    &pretty=1"

Combining Filters

When you use multiple filters:

• Multiple values in a single filter use OR logic (e.g., match[risk]=high,critical returns high OR critical risk)
• Multiple different filters use AND logic (e.g., match[risk]=high&match[itype]=domain returns high risk AND domain type)

Example: Multiple Filters

This request combines risk levels, indicator types, and status:

# Get active, high-risk domains and URLs from the test collection
curl "https://pulsedive.com/taxii2/api/collections/981c4916-ebb2-4567-aece-54ae970c4230/objects/ \
    ?key=<YOUR_API_KEY> \
    &accept=application/taxii+json;version=2.1 \
    &match[risk]=high,critical \
    &match[itype]=domain,url \
    &match[retired]=false \
    &limit=10 \
    &pretty=1"

This query returns indicators that match:

• (high risk OR critical risk) AND
• (domain type OR url type) AND
• (not retired)