Flow Logs

Retrieve Flow Logs by destination

Beta
<Info icon="fa-light fa-lock" className="permission-callout"> <div className="permission-callout__header"><span className="permission-callout__title"><span className="permission-callout__label">Required permissions</span> <span className="fern-docs-badge small blue subtle rounded-full permission-callout__beta">Beta</span></span> <span className="permission-callout__learn-more">[Learn more](/developers/api-guidelines/permissions#how-permissions-work)</span></div> `Endpoint.FlowLogs.Destination` + `List` <div className="permission-callout__roles"><span className="permission-callout__roles-label">Roles:</span> <Badge intent="info">Administrator</Badge></div> </Info> Retrieves Flow Log activity for an endpoint, grouped by destination hostname, IP address, port, and protocol. By default, the response covers the last hour. Use `started_from` in the `q` parameter to look back up to **30 days**. Filters follow the standard `q=<field>:<criteria>` syntax: - Combine multiple filters on different fields with `,` (AND). - Combine multiple values for the same field with `||` (OR). Use `sort` to order the results and `page` / `per_page` to paginate.

Authentication

AuthorizationBearer

An auth_token should be provided to authenticate a session.

To obtain an auth_token, see the /api/v1/authenticate POST request.

Path parameters

endpointIddoubleRequired

Query parameters

per_pageintegerOptional1-100Defaults to 25
Number of destination groups to return per page.
pageintegerOptional>=1Defaults to 1

Page number to retrieve. Starts at 1.

sortstringOptionalformat: "(^-?(destination_hostname| destination_ip| destination_port| protocol| started_on| completed_on| bytes_up| bytes_down)),?"Defaults to -started_on
Sorts destination groups by field value. Use `<operator><field>` format. Operators: `-` descending, `+` ascending. <Tip> You can also combine multiple sort fields with commas (for example, `-started_on,destination_hostname`). </Tip>
qstringOptionalformat: "(destination_hostname| destination_ip| destination_port| protocol| started_from| started_until| completed_from| completed_until):.+"
Filters destination groups by field value. Use `<field>:<criteria>` format. Combine multiple filters with commas (for example, `protocol:TCP,destination_hostname:api.example.com`). Use `||` within one field for multiple values (for example, `protocol:TCP||UDP`). Time window (optional, each as `<field>:<ISO-8601 UTC>`): - `started_from` - Lower bound on flow start - Defaults to 1 hour ago - Maximum look-back 30 days. - `started_until` - Upper bound on flow start - Defaults to now. - `completed_from` / `completed_until` - Bounds on flow completion time. <Warning> Window fields must use `:` only (no other operators). </Warning>

Response headers

X-SortstringOptional
Applied sort field from the sort parameter.
X-FilterstringOptional

Applied filter criteria from the q parameter.

x-current-pageinteger
Current page number.
x-count-per-pageinteger
Number of destination groups per page.
x-total-pagesinteger
Total number of pages.
x-total-countinteger
Total number of destination groups matching the query.

Response

Destination groups for the requested window.
destination_hostnamestring or nullOptional
Hostname of the destination, if resolved.
destination_ipstringOptional
IP address of the destination.
destination_portintegerOptional
Destination port number.
protocolstringOptional

Transport protocol (for example, TCP, UDP).

started_onstringOptionalformat: "date-time"
Earliest start time across the aggregated flows.
completed_onstringOptionalformat: "date-time"
Latest completion time across the aggregated flows.
bytes_upintegerOptional
Total bytes uploaded to the destination.
bytes_downintegerOptional
Total bytes downloaded from the destination.
flow_countintegerOptional
Number of flows aggregated into this destination group.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error