> This page is for Developers. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.emnify.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emnify.com/_mcp/server. > Flow Logs developer reference for the emnify REST API — the destination-aggregated and per-flow detail objects, their fields, enums, filtering, sorting, and pagination. 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](/multicloud-data-streamer/stream-types#flow-logs-flow-data). 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](/system-events/event-types/flow-logs). > **Note** > > 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=:` syntax. Combine multiple values for one field with `||`, and combine different fields with `,`. * **Sorting**: use `sort=`, 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 ```http 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](#protocol-values). Unknown IANA numbers are returned as `PROTO_`. | | `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 ```json [ { "destination_hostname": "api.example.com", "destination_ip": "192.0.2.10", "destination_port": 443, "protocol": "TCP", "started_on": "2026-05-11T13:42:17.000Z", "completed_on": "2026-05-11T13:58:04.000Z", "bytes_up": 18432, "bytes_down": 245760, "flow_count": 27 }, { "destination_hostname": null, "destination_ip": "203.0.113.45", "destination_port": 53, "protocol": "UDP", "started_on": "2026-05-11T13:40:02.000Z", "completed_on": "2026-05-11T13:55:11.000Z", "bytes_up": 1840, "bytes_down": 5120, "flow_count": 12 } ] ``` ## Flow Log detail ```http GET /api/v1/endpoint/{endpointId}/flowlogs/detail ``` Returns individual (non-aggregated) flow rows. This is the data behind a device's [Flow Log details](/portal/connected-devices#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](#protocol-values). Unknown IANA numbers are returned as `PROTO_`. | | `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 ```json [ { "flow_id": "a1b2c3d4-e5f6-4890-abcd-ef0123456789", "organisation_id": 100, "endpoint_id": 1, "started_on": "2026-05-11T13:42:17.000Z", "completed_on": "2026-05-11T13:58:04.000Z", "duration_seconds": 947, "event_type": "flow_start", "direction": "ingress", "source_ip": "10.0.0.5", "source_port": 51234, "destination_ip": "192.0.2.10", "destination_port": 443, "protocol": "TCP", "bytes_up": 18432, "bytes_down": 245760, "destination_hostname": "api.example.com", "destination_hostname_source": "TLS_SNI", "nat_details": { "public_ip": "203.0.113.4" }, "pdp_context": { "mcc": "262", "mnc": "01", "apn": "em", "imsi": "262011234567890", "country": { "name": "Germany", "country_code": "49", "iso_code": "de", "id": 74 }, "operator": { "id": "26201", "name": "Telekom Deutschland" } }, "release_details": { "release_side": "server", "release_reason": "tcp_fin" }, "session_id": "pdp-9f3c1b27", "last_loaded_at": "2026-05-11T14:00:00.000Z" } ] ``` ## Protocol values The `protocol` field is the symbolic name for the flow's IANA protocol number. Numbers without a mapping are returned as `PROTO_` 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` |