flow_summary
Summarize one host's network conversations: top peers, top ports, and a client-vs-service-side split, each with a residual "other" bucket plus overall totals. Wraps GET /api/aggnetflow/summary (permission: vne). Use this to characterize a host before pulling rows — netflow_search returns the individual conversations once a rollup here points at an interesting peer or port.
Source is the windowed flow view: the raw table's live tail (the last ~15 minutes — cleanup_netflow deletes raw rows as it rolls them up) unioned with the aggregated history (agg_netflow, retained 4 weeks), so one call covers right-now through a month back with no gap at the rollup boundary.
Byte totals are IN-WINDOW estimates, not lifetime totals. The window predicate is OVERLAP — a conversation crossing either edge still matches — but each matching row contributes only its bytes pro-rated to the window (uniform-rate attribution), so the totals approximate window traffic instead of bounding it from above. Still never quote a byte figure as a rate.
Direction is normalized on both arms (the lower port of each conversation becomes dst_port — raw-tail rows are re-oriented the same way on read) and the rollup folds BOTH directions into one row, so sent-vs-received bytes do not exist in this data. The direction split is as_source (host was the client side) vs as_destination (host was the service side), each carrying bidirectional bytes.
conversations counts rows, not distinct conversations — a long-lived conversation contributes one row per 15-minute roll-up tick, plus per-flow rows for its not-yet-rolled-up raw tail.
Window: hours (default 24, max 168) OR start_time+end_time; an explicit window is held to the same 168-hour ceiling server-side — agg_netflow is BRIN-indexed on time now, but a summary still aggregates every overlapping row under a 10s statement timeout. A window too wide comes back as an error asking you to narrow it, not as partial data.
limit is the top-N per rollup (default 20, max 100); what falls outside it is reported in that rollup's other bucket, so totals always reconcile.
Tag-scoped server-side on the conversation ENDPOINTS: for a tag-restricted caller every returned conversation has an in-tag device on one side. The requested host gets no separate membership test, so naming an out-of-scope host is allowed and simply returns the subset of its conversations that touch a device you can already see.
Example: flow_summary({ip: '10.0.0.5', hours: 24, limit: 10})
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | REQUIRED. The host to summarize. Matched on either side of the conversation (src_ip OR dst_ip) — no direction needs to be known or guessed. | |
| hours | No | Lookback hours (1-168). Default 24. | |
| limit | No | Top-N entries per rollup (1-100). Default 20. The remainder is summarized in each rollup's `other` bucket. | |
| end_time | No | ISO-8601 UTC; pairs with start_time. | |
| start_time | No | ISO-8601 UTC; pairs with end_time. The span is still capped at 168 hours. |