Guide

Filtering Events

Narrow the event stream before delivery with subscription scopes, filter rules, and importance thresholds.

Kite has three layers of filtering. Pick the one that matches how much you care about latency, network traffic, and per-event compute.

Layer	Where it runs	What it does
Subscriptions	WebSocket request + CLI manifest filter	The CLI requests a narrower stream and then applies manifest subscriptions before delivery
Filter rules	CLI, before delivery	Drop rules run first; `keep_only` rules run next
Importance threshold	CLI, after scoring	Only deliver events scored at or above a minimum importance

// 01Subscriptions

Subscriptions live at the top of a manifest. The CLI uses them to request a narrower WebSocket stream and also checks the manifest subscription entries before delivery.

json

{
  "name": "my-agent",
  "subscriptions": [
    { "source": "github" },
    { "type": "com.stripe.payment_intent.succeeded" }
  ],
  "sink": { "type": "proxy", "target": "http://localhost:3000/webhooks" }
}

Entries are OR'd. The CLI's ad-hoc equivalents are --source and --event-type:

bash

kite stream --source github --event-type com.github.push

// 02Filter rules (CLI, pre-delivery)

The manifest filters block runs on the CLI just before the sink. Use it when you still want the events counted in your dashboard but not delivered to your app.

json

{
  "filters": {
    "drop": [
      { "source": "github", "type": "com.github.ping" },
      { "actor": "dependabot\\[bot\\]" }
    ],
    "keep_only": [
      { "source": "github", "type": "com.github.push" },
      { "source": "github", "type": "com.github.pull_request.*" }
    ]
  }
}

Rule fields

All fields are optional; they're AND'd together. source, type, actor, and ref support glob patterns (*, **).

Field	Matches
`source`	Source name (e.g. `"github"`, `"stripe"`)
`type`	CloudEvent type (e.g. `"com.github.pull_request.*"`)
`actor`	GitHub sender login (e.g. `"dependabot\\[bot\\]"`)
`ref`	Git ref (e.g. `"refs/heads/main"`)

Order of operations

1. drop — if any rule matches, the event is dropped and the pipeline stops. 2. keep_only — if the list is non-empty and no rule matches, the event is dropped.

Leave keep_only off when you only want to prune a few noisy event types.

// 03Importance threshold (CLI, post-scoring)

Combine filters with the scoring block and then gate delivery on importance. This is the right layer for "page me only when something matters".

json

{
  "scoring": {
    "rules": [
      {
        "match": { "source": "github", "type": "com.github.push" },
        "paths": ["src/auth/*", "migrations/*"],
        "importance": "critical",
        "reason": "auth/migration push"
      }
    ],
    "default_importance": "normal"
  },
  "sink": {
    "type": "exec",
    "command": "./page-oncall.sh",
    "importance": "high"
  }
}

The sink.importance field (low, normal, high, critical) drops anything below the threshold after manifest scoring. From the CLI, kite stream --importance high filters events that already carry an importance value; it does not run manifest scoring by itself.

// 04Dedup

kite run can collapse duplicate events before delivery:

json

{
  "scoring": {
    "dedup": {
      "window": "10m",
      "key": ["source", "type", "ref", "actor"],
      "strategy": "keep_last"
    }
  }
}

Duplicate events are still stored in the local queue, marked filtered, and acknowledged to Kite so the cursor can advance. Use keep_first to keep the original duplicate timestamp, or keep_last to refresh the duplicate window when repeated events arrive.

// 05See also

Manifest Schema — full field reference
Agent Pipelines — tutorial that wires filters, enrichment, and scoring end-to-end