# Flow

A flow is a representation of network traffic. When data is sent through your network, Flows tells you when, on which device, how much data was uploaded or downloaded, and more. It is one of Firewalla’s fundamental concepts. A flow is always associated with a device (including VPN profile, which counts as a device as well) and a remote host.

There's also Blocked Flows, which have very similar structure to Flows but represent traffic that Firewalla has blocked. Since Blocked Flows are intercepted before traveling through your network, they don’t have upload or download information.

## Get Flows
Gets all flows with given conditions. Flows are always returned in reverse chronological order.

[!badge variant="primary" text="GET"] <span style="color:grey">https://msp_domain</span>**/v2/flows**

<p class="header">Header</p>

| Name                                                       | Value                 |
| ---------------------------------------------------------- | --------------------- |
| Authorization <span style="color:orange">*required*</span> | Personal access token |

<p class="header">Query String</p>

| Name                                        | Value                                                                                                                 |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| query                                       | The search query. See [Query basics](./search.md#flow-qualifiers)                                                  |
| groupBy                                     | Grouping the flows based on the  given values. A comma-separated list. e.g., `domain,box`                             |
| sortBy                                      | Sorting the flows based on the given values. A comma-separated list. e.g., `ts:desc,total:asc`. Defaults to `ts:desc` |
| limit <span style="color:grey"><=500</span> | Max number of results being returned. Defaults to `200`                                                               |
| cursor                                      | See [Pagination](./search.md#pagination)                                                                              |

<p class="response">Response</p>

<p class="statusCode"><svg class="green" viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>200 Success</span>
</p>

| Name          | Type                                   | Description                                                                                        |
| ------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `count`       | Number                                 | Number of results in the response                                                                  |
| `results`     | [Flow](../data-models/flow.md/#flow)[] | List of flows being returned, its length is always no more than then `limit` specified in the request |
| `next_cursor` | String                                 | See [Pagination](./search.md#pagination)                                                           |

```json
{
  "count": 1,
  "results": [
    {
      "ts": 1647550615.011,
      "gid": "00000000-1234-1234-aaaa-000000000000",
      "protocol": "tcp",
      "direction": "outbound",
      "block": false,
      "download": 1000,
      "upload": 500,
      "duration": 0.77,
      "category":"shopping",
      "count": 1,
      "region":"CN",
      "device": {
        "id": "AA:BB:CC:DD:EE:FF",
        "ip": "192.168.210.110",
        "name": "My Iphone",
        "port": "55664"
      },
      "network": {
          "id": "99285a11-aaaa-bbbb-cccc-510596edaaaa",
          "name": "Home Office"
        },
      "group": {
          "id": "2",
          "name": "Mobile"
        },
      "source": {
        "id": "AA:BB:CC:DD:EE:FF",
        "ip": "192.168.210.110",
        "name": "My Iphone"
      },
      "destination":{
        "id": "firewalla.com",
        "ip": "23.227.38.32",
        "name": "firewalla.com"
      }
    }
  ],
  "next_cursor": null
}

```

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>401 Permission Denied</span>
</p>

<p class="examples">Examples</p>

- [Flow Pagination](https://github.com/firewalla/msp-api-examples/tree/main/flow-pagination), `Query String` `Pagination`