Attribute Based Filters API

Manage attribute based filters for the active Organizational Unit. Attribute based filters suppress events whose metadata matches a set of key/value conditions, excluding them from scoring, session creation, and lead creation before velocity checks run.

These endpoints correspond to the Configure > Filters > Attribute Based tab in the kenbun UI.

For velocity based (inorganic activity) filter endpoints, see Velocity Based Filters.

---

GET /metadata-filters

List all attribute based filters for the active Organizational Unit.

Response

200 OK

Returns an array of filter objects, sorted with enabled filters first and most recently updated first.

Field	Type	Description
id	string	Unique filter identifier
name	string	Human-readable name for the filter
event_type	string	Event type this filter is scoped to. Empty string means the filter applies to all event types
conditions	array	List of key/value conditions (see Condition Object)
enabled	boolean	Whether the filter is currently active
suppressed_count	integer	Total number of events suppressed by metadata attribute filters in this OU
created_at	timestamp	When the filter was created
updated_at	timestamp	When the filter was last modified
created_by	string	Email of the user who created the filter
updated_by	string	Email of the user who last modified the filter

Example

curl -X GET "https://api.kenbun.io/metadata-filters" \
  -H "Authorization: Bearer <token>"

[
  {
    "id": "mf-abc123",
    "name": "Block Search Crawlers",
    "event_type": "Page View",
    "conditions": [
      { "key": "user_agent", "operator": "contains", "value": "bot" }
    ],
    "enabled": true,
    "suppressed_count": 482,
    "created_at": "2026-01-10T09:00:00Z",
    "updated_at": "2026-01-10T09:00:00Z",
    "created_by": "ops@example.com",
    "updated_by": "ops@example.com"
  }
]

---

POST /metadata-filters

Create a new attribute based filter.

Request Body

Field	Type	Required	Description
name	string	Yes	Human-readable name for the filter
event_type	string	No	Scope this filter to one event type. Omit or send empty string to apply to all event types
conditions	array	No	List of condition objects (see Condition Object). A filter with no conditions will match nothing
enabled	boolean	No	Set to false to create the filter in a disabled state (default: true)

Response

201 Created — Returns the created filter object.

Example

curl -X POST "https://api.kenbun.io/metadata-filters" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Block Search Crawlers",
    "event_type": "Page View",
    "conditions": [
      { "key": "user_agent", "operator": "contains", "value": "bot" }
    ],
    "enabled": true
  }'

Common Errors

Status	Meaning	Solution
400	Missing name or invalid regex	Provide a name and check any matches_regex conditions for valid patterns
401	Unauthorized	Check your API credentials

---

GET /metadata-filters/{id}

Retrieve a single attribute based filter by ID.

Request

Parameter	Type	Required	Description
id	string	Yes	Filter identifier (path parameter)

Response

200 OK — Returns the filter object.

Example

curl -X GET "https://api.kenbun.io/metadata-filters/mf-abc123" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
404	Not Found	Verify the filter ID and that it belongs to the active OU

---

PUT /metadata-filters/{id}

Update an existing attribute based filter. All fields in the request body replace the current values.

Request

Parameter	Type	Required	Description
id	string	Yes	Filter identifier (path parameter)

Request Body

Field	Type	Required	Description
name	string	Yes	Updated name
event_type	string	No	Updated event type scope. Send empty string to remove scoping
conditions	array	No	Replacement list of condition objects
enabled	boolean	No	Enable or disable the filter

Response

200 OK — Returns the updated filter object.

Example

curl -X PUT "https://api.kenbun.io/metadata-filters/mf-abc123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Block All Bot Traffic",
    "event_type": "",
    "conditions": [
      { "key": "user_agent", "operator": "contains", "value": "bot" },
      { "key": "user_agent", "operator": "contains", "value": "crawler" }
    ],
    "enabled": true
  }'

Common Errors

Status	Meaning	Solution
400	Missing name or invalid regex	Provide a name and check matches_regex conditions
404	Not Found	Verify the filter ID

---

DELETE /metadata-filters/{id}

Delete an attribute based filter. This action cannot be undone. To temporarily stop a filter without losing its configuration, use PUT to set enabled: false instead.

Request

Parameter	Type	Required	Description
id	string	Yes	Filter identifier (path parameter)

Response

204 No Content

Example

curl -X DELETE "https://api.kenbun.io/metadata-filters/mf-abc123" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
404	Not Found	Verify the filter ID

---

POST /metadata-filters/preview

Preview how many existing events would be suppressed by a set of conditions, without saving any changes. Use this before creating or updating a filter to verify scope.

Request Body

Field	Type	Required	Description
event_type	string	No	Scope the preview to a specific event type. Omit to check all event types
conditions	array	Yes	List of condition objects to evaluate (see Condition Object)

Response

200 OK

{ "count": 482 }

Field	Type	Description
count	integer	Number of existing events that match the provided conditions

Example

curl -X POST "https://api.kenbun.io/metadata-filters/preview" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "Page View",
    "conditions": [
      { "key": "user_agent", "operator": "contains", "value": "bot" }
    ]
  }'

---

Condition Object

Each condition in the conditions array has the following shape:

Field	Type	Required	Description
key	string	Yes	The metadata field name to evaluate (e.g., user_agent, source, environment)
operator	string	Yes	Comparison operator (see table below)
value	string	No	The value to compare against. Not required for is_empty and is_not_empty operators

Operators

Operator	Description
equals	Exact match
not_equals	Does not match
contains	Field value includes the string (case-insensitive)
not_contains	Field value does not include the string
starts_with	Field value begins with the string
ends_with	Field value ends with the string
matches_regex	Field value matches the regular expression
is_empty	Field is absent or blank
is_not_empty	Field is present and non-blank

All conditions in a filter must match for an event to be suppressed (AND logic).

Example Condition

{ "key": "user_agent", "operator": "contains", "value": "Googlebot" }

---

Notes

• Filters are scoped to the active Organizational Unit. Filters created in one OU are not visible in others.
• Attribute based filters evaluate before velocity based filters. An event suppressed by a metadata condition never enters the velocity pipeline.
• Suppressed events are stored but excluded from scoring, session creation, and lead creation. Their suppression_reason field is set to "metadata_filter".
• Filters apply to new events only. Previously ingested events are not retroactively re-evaluated when a filter is created or updated.

Related

• Attribute Based Filters Guide — UI walkthrough and configuration examples
• Velocity Based Filters — Suppress events by rate thresholds
• Events — The suppression_reason field on event responses