Skip to main content
An exclusion tells one monitor which results you don’t need to see: your own test listings, a partner’s domain, a seller you already track. Each exclusion belongs to a single monitor. In the paths below, alert_rule_id is the monitor’s ID. Exclusions work forward only. A monitor checks its exclusions when a run records a match. Adding an exclusion does not flag rows already recorded, and removing one does not unflag them. A flagged row is kept, with is_excluded: true, and hidden by default when you read matches. Send show_excluded=true to see it. A match whose rows are all excluded sends no email and no webhook.
These are monitor exclusions. Attack Surface assessments have their own exclusion rules, and Domain monitoring has trusted domains. None of the three affects the others.

​
Availability and cost

Availability: every plan with a license in force. Cost: no metered allowance. With an API key, each call counts once toward your monthly API Calls allowance, and only 2xx responses count. See Rate limits. When your organization’s license is not active, every endpoint on this page returns 403:
A monitor ID that does not belong to your organization, or a monitor you deleted, returns 404. See Plans and quotas and Errors.

​
Find the fields a source can exclude

A source supports exclusions when its entry in the service catalog lists excludable_fields. Each entry names a field and the comparison used for it: The Data Brokers source, for example, declares:
A source with an empty list accepts no exclusions. Every condition you send for it is refused.

​
How a condition matches

An exclusion is a condition built from two shapes:
  • A rule tests one field: {"field": "seller", "value": "Acme Reseller"}.
  • A group combines rules or other groups: {"match": "all", "rules": […]}. all means every entry must match (AND). any means at least one must match (OR).
Groups can nest. The top level of every exclusion is a group. When a run records a row, the monitor looks for the rule’s field by key name anywhere in the row’s data, at any depth. When that key holds a list or an object, each text or number value inside it is tested. One hit is enough. The comparison comes from the source’s excludable_fields, not from your request.

​
Add exclusions

alert-system-exclusions-create takes a non-empty JSON array with one group per exclusion. Exclude one seller from monitor 45:
Exclude a row only when two fields match together:
Exclude any of several values in one exclusion:
A 201 returns one entry for each item you sent, each with id, condition and created_at:
Exclusions are unique per monitor. Sending a condition the monitor already has creates nothing and returns the existing exclusion in the response.

​
How conditions are stored

The monitor normalizes each condition before it stores it and before it checks for duplicates. condition in every response shows the stored form.
  • The field name is matched ignoring case and stored in the source’s spelling, so Seller becomes seller.
  • The value is trimmed. For iexact and icontains fields it is also lowercased.
  • The entries of each group are sorted.
Two conditions that differ only in rule order, surrounding spaces, or letter case on a case-insensitive field are the same exclusion.

​
When a request is refused

A 400 can leave some exclusions saved. Items are checked and saved one at a time, in order, so every item before the refused one is already stored. After a 400, list the monitor’s exclusions to see what was saved. Sending the whole array again is safe once you fix it, because an existing condition is never stored twice.

​
Upload a list

To exclude many values at once, send a CSV file to alert-system-exclusions-upload as the multipart field file:
The first row holds field names. Every row after it becomes one exclusion:
Each row combines its non-empty cells into one group with the match you send: all (every cell must match) or any (one is enough). With match=all, the row acme-market,test excludes results whose site_name is acme-market and whose data_type contains test. Always send match. The reference lists it as required, but a request without it is read as any, so each row then excludes results that match any one of its cells. Any value other than all or any returns 400 with {"error": "match must be 'all' or 'any'."}. How the file is read:
  • It must be a .csv file, 5 MB or smaller, encoded in UTF-8. A byte-order mark is accepted.
  • Cells are separated by commas. If the header row contains a tab, the file is read as tab-separated.
  • Only the first 1,000 rows after the header are read. Later rows are ignored without an error and are not counted. Split a longer list into several files.
  • Empty cells are skipped. A row with no values is skipped and not counted. A column with an empty header is ignored.
  • A row that has a value under a field the source cannot exclude is skipped whole, even when its other cells are valid.
  • A row is stored in the same normalized form as a condition you add by hand.
A 201 summarizes the upload:
A file the monitor cannot read returns 400 with the file name and the reason, for example {"error": "exclusions.csv: File exceeds 5 MB limit"}. The reasons are File must be .csv, File exceeds 5 MB limit, File must be UTF-8 encoded, File is empty, File must have a header row with at least one field name and File must have at least one non-empty value.

​
List, read and remove

An exclusion cannot be edited. To change one, remove it and add the new condition.

​
Endpoints