Flow Logs | emnify Documentation

Flow Logs are metadata-only network flow records generated by devices across emnify’s mobile core. You can access them through the emnify Portal, the REST API, and the Data Streamer.

This page documents the REST API representation of Flow Logs. For the streaming event schema delivered by the Data Streamer (the flow_start, flow_update, and flow_end records), see Network Flow Logs.

Flow Logs are a subscribable enterprise service that must be enabled for your organization. Requests return 403 Forbidden if the feature isn’t enabled or you lack permission.

The REST API exposes Flow Logs for a single device through two endpoints:

Endpoint	Description
`GET /api/v1/endpoint/{endpointId}/flowlogs/destination`	Flow activity aggregated by destination (hostname, IP, port, and protocol).
`GET /api/v1/endpoint/{endpointId}/flowlogs/detail`	Individual, non-aggregated flow rows.

Both endpoints share the same conventions:

Time window: results default to the last hour. Use started_from (and the other time bounds) to widen it, up to a maximum look-back of 30 days.
Filtering: use the q=<field>:<criteria> syntax. Combine multiple values for one field with ||, and combine different fields with ,.
Sorting: use sort=<operator><field>, where - is descending and + (or no operator) is ascending. Separate multiple sort fields with ,. Both endpoints default to -started_on.
Pagination: use page (starts at 1) and per_page. Responses include the X-page, X-per-page, X-pages, X-count, X-Sort, and X-Filter headers.

Flow Logs by destination

1 GET /api/v1/endpoint/{endpointId}/flowlogs/destination

Returns flow activity for a device aggregated by the combination of destination hostname, destination IP, destination port, and protocol.

Property	Type	Description
`destination_hostname`	String or null	Destination hostname when DNS was resolved, otherwise `null`.
`destination_ip`	String	Destination IP address (IPv4 or IPv6).
`destination_port`	Integer	Destination TCP/UDP port.
`protocol`	String	Transport protocol name. Unknown IANA numbers are returned as `PROTO_<n>`.
`started_on`	String (date-time)	Earliest period start in the group (ISO-8601 UTC).
`completed_on`	String (date-time)	Latest period end in the group (ISO-8601 UTC).
`bytes_up`	Integer	Total bytes uploaded across the grouped flows.
`bytes_down`	Integer	Total bytes downloaded across the grouped flows.
`flow_count`	Integer	Number of raw flow rows aggregated into the group.

Filter fields: destination_hostname, destination_ip, destination_port, protocol, started_from, started_until, completed_from, completed_until.
Sort fields: destination_hostname, destination_ip, destination_port, protocol, started_on, completed_on, bytes_up, bytes_down.
per_page: maximum 100 (default 25).

Example response

1 [
2   {
3     "destination_hostname": "api.example.com",
4     "destination_ip": "192.0.2.10",
5     "destination_port": 443,
6     "protocol": "TCP",
7     "started_on": "2026-05-11T13:42:17.000Z",
8     "completed_on": "2026-05-11T13:58:04.000Z",
9     "bytes_up": 18432,
10     "bytes_down": 245760,
11     "flow_count": 27
12   },
13   {
14     "destination_hostname": null,
15     "destination_ip": "203.0.113.45",
16     "destination_port": 53,
17     "protocol": "UDP",
18     "started_on": "2026-05-11T13:40:02.000Z",
19     "completed_on": "2026-05-11T13:55:11.000Z",
20     "bytes_up": 1840,
21     "bytes_down": 5120,
22     "flow_count": 12
23   }
24 ]

Flow Log detail

1 GET /api/v1/endpoint/{endpointId}/flowlogs/detail

Returns individual (non-aggregated) flow rows. This is the data behind a device’s Flow Log details in the Portal.

Property	Type	Description
`flow_id`	String	Identifier of the flow that produced the row.
`organisation_id`	Integer	Organization that owns the endpoint.
`endpoint_id`	Integer	Endpoint the row belongs to.
`started_on`	String (date-time) or null	Row start timestamp (`period_start_ts`, ISO-8601 UTC).
`completed_on`	String (date-time) or null	Row end timestamp (`period_end_ts`, ISO-8601 UTC).
`duration_seconds`	Integer or null	Whole seconds from `started_on` to `completed_on`. `null` when either bound is missing.
`event_type`	String or null	One of `flow_start`, `flow_update`, or `flow_end`.
`direction`	String or null	Traffic direction: `ingress` or `egress`.
`source_ip`	String or null	Source IP address (IPv4 or IPv6).
`source_port`	Integer or null	Source TCP/UDP port.
`destination_ip`	String or null	Destination IP address (IPv4 or IPv6).
`destination_port`	Integer or null	Destination TCP/UDP port.
`protocol`	String or null	Transport protocol name. Unknown IANA numbers are returned as `PROTO_<n>`.
`bytes_up`	Integer or null	Bytes uploaded for the row.
`bytes_down`	Integer or null	Bytes downloaded for the row.
`destination_hostname`	String or null	Destination hostname when DNS was resolved, otherwise `null`.
`destination_hostname_source`	String or null	How the hostname was resolved (for example, `TLS_SNI` or `reverse_dns`).
`nat_details`	Object or null	NAT translation details (for example, `public_ip`).
`pdp_context`	Object or null	Mobile network context: `mcc`, `mnc`, `apn`, `imsi`, `country` (`name`, `country_code`, `iso_code`, `id`), and `operator` (`id`, `name`).
`release_details`	Object or null	Session release details: `release_side` and `release_reason`.
`session_id`	String or null	PDP session identifier associated with the flow.
`last_loaded_at`	String (date-time) or null	When the row was last loaded (ISO-8601 UTC).

Filter fields: destination_hostname, destination_ip, destination_port, protocol, flow_id, event_type, started_from, started_until, completed_from, completed_until.
Sort fields: started_on, completed_on, destination_hostname, destination_ip, destination_port, protocol, bytes_up, bytes_down.
per_page: maximum 1000 (default 25).

Example response

1 [
2   {
3     "flow_id": "a1b2c3d4-e5f6-4890-abcd-ef0123456789",
4     "organisation_id": 100,
5     "endpoint_id": 1,
6     "started_on": "2026-05-11T13:42:17.000Z",
7     "completed_on": "2026-05-11T13:58:04.000Z",
8     "duration_seconds": 947,
9     "event_type": "flow_start",
10     "direction": "ingress",
11     "source_ip": "10.0.0.5",
12     "source_port": 51234,
13     "destination_ip": "192.0.2.10",
14     "destination_port": 443,
15     "protocol": "TCP",
16     "bytes_up": 18432,
17     "bytes_down": 245760,
18     "destination_hostname": "api.example.com",
19     "destination_hostname_source": "TLS_SNI",
20     "nat_details": { "public_ip": "203.0.113.4" },
21     "pdp_context": {
22       "mcc": "262",
23       "mnc": "01",
24       "apn": "em",
25       "imsi": "262011234567890",
26       "country": { "name": "Germany", "country_code": "49", "iso_code": "de", "id": 74 },
27       "operator": { "id": "26201", "name": "Telekom Deutschland" }
28     },
29     "release_details": { "release_side": "server", "release_reason": "tcp_fin" },
30     "session_id": "pdp-9f3c1b27",
31     "last_loaded_at": "2026-05-11T14:00:00.000Z"
32   }
33 ]

Protocol values

The protocol field is the symbolic name for the flow’s IANA protocol number. Numbers without a mapping are returned as PROTO_<n> so no information is lost.

Number	Name
1	`ICMP`
2	`IGMP`
6	`TCP`
17	`UDP`
41	`IPV6`
47	`GRE`
50	`ESP`
51	`AH`
58	`ICMPV6`
89	`OSPF`
132	`SCTP`