---
name: azion-query-live-ingest-connected-users
description: >-
  Query the connectedUsersMetrics dataset of the GraphQL API for the unique sessions of your Live Ingest streams, per host or as a total across hosts.
---

# Query Live Ingest connected users

You can count the unique sessions connected to your Live Ingest streams with the `connectedUsersMetrics` dataset of the GraphQL API, per host or as a total across all hosts. The dataset holds aggregated data that Live Ingest provides, and the metrics endpoint, `https://api.azion.com/v4/metrics/graphql`, serves it. Use the results to review audience activity, or move them to another platform for analysis.

---

## Prerequisites

- A Live Ingest subscription on your account. For what Live Ingest does, refer to [Connectors](/en/documentation/platform/connectors/#live-ingest).
- A [personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/) for your account.
- A way to send a GraphQL query, such as GraphiQL or `curl`. For more information, refer to [GraphQL API quickstart](/en/documentation/devtools/graphql/first-steps/).

---

## Query unique sessions by host

Group the rows by `ts` and `host` to read the unique sessions of each host at each timestamp. To query the sessions by host:

1. **Write the query**

   This query reads the sessions of every host in a one-day window, newest first. Replace the `begin` and `end` values with your window:

   ```graphql
   query ConnectedUsers {
     connectedUsersMetrics(
       limit: 10000,
       filter: {
         tsRange:{
           begin: "2024-04-10T00:00:00",
           end: "2024-04-11T00:00:00"
         }
       },
       groupBy: [ts,host]
       orderBy: [ts_DESC]
     ) {
       ts,
       host,
       uniqueSessions
     }
   }
   ```

   The query uses these arguments:

   | Argument  | What it sets                                                                                                                                         |
   | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `limit`   | The maximum number of rows to return, from `0` to `10000`. Without it, the API returns at most `10` rows.                                            |
   | `filter`  | The criteria the rows must match. A time filter is required. `tsRange` takes a `begin` and an `end` timestamp in the format `"YYYY-MM-DDTHH:mm:ss"`. |
   | `groupBy` | The fields that group the rows: `ts`, `host`, or both. `[ts,host]` returns one row per timestamp and host.                                           |
   | `orderBy` | The sort order of the rows. `[ts_DESC]` returns the newest timestamp first, `[ts_ASC]` the oldest first.                                             |

   The `connectedUsersMetrics` dataset does not take the `resample` argument.

2. **Send the query**

   Send the query in a `POST` request to `https://api.azion.com/v4/metrics/graphql`, with the header `Authorization: Token [TOKEN VALUE]`.

3. **Read the response**

   The response holds one object per timestamp and host in `data.connectedUsersMetrics`, with the fields the query selects:

   | Field            | Type             | Description                                                                                                                                              |
   | ---------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `ts`             | `CustomDateTime` | The timestamp of the data point.                                                                                                                         |
   | `host`           | `String`         | The host of the request: the host name from the request line, the host name from the `Host` request header, or the server name that matches the request. |
   | `uniqueSessions` | `Int`            | The unique sessions counted for the host.                                                                                                                |

The API answers with HTTP `200` and returns the rows in `data.connectedUsersMetrics`.

---

## Query the total across hosts

The `uniqueSessionsTotal` field counts the unique sessions across all hosts, so the query groups the rows by `ts` alone and leaves `host` out. To query the total sessions:

1. **Write the query**

   This query reads the total sessions in a one-day window, newest first. Replace the `begin` and `end` values with your window:

   ```graphql
   query ConnectedUsers {
     connectedUsersMetrics(
       limit: 10000,
       filter: {
         tsRange:{
           begin: "2024-04-10T00:00:00",
           end: "2024-04-11T00:00:00"
         }
       },
       groupBy: [ts]
       orderBy: [ts_DESC]
     ) {
       ts,
       uniqueSessionsTotal
     }
   }
   ```

   `limit` takes up to `10000` rows, `filter` requires a time filter such as `tsRange`, and `orderBy` takes `[ts_DESC]` or `[ts_ASC]`. `groupBy: [ts]` returns one row per timestamp.

2. **Send the query**

   Send the query in a `POST` request to `https://api.azion.com/v4/metrics/graphql`, with the header `Authorization: Token [TOKEN VALUE]`.

3. **Read the response**

   The response holds one object per timestamp in `data.connectedUsersMetrics`, with the fields the query selects:

   | Field                 | Type             | Description                                   |
   | --------------------- | ---------------- | --------------------------------------------- |
   | `ts`                  | `CustomDateTime` | The timestamp of the data point.              |
   | `uniqueSessionsTotal` | `Int`            | The unique sessions counted across all hosts. |

The API answers with HTTP `200` and returns the rows in `data.connectedUsersMetrics`.

---

## Next steps

- [Real-Time Metrics fields](/en/documentation/devtools/graphql/gql-real-time-metrics-fields.md): Look up every field of connectedUsersMetrics and the other metrics datasets.
- [How the GraphQL API works](/en/documentation/devtools/graphql/overview.md): See how long each dataset keeps its data and how time buckets work.
- [GraphQL API limits](/en/documentation/devtools/graphql/limits.md): Check the row and field limits that apply to every query.
- [Ingestion and delivery](/en/documentation/platform/connectors/live-ingest/ingestion-and-delivery.md): See how Live Ingest takes a stream from your encoder to viewers.