# How to query Connected Users data with GraphQL API

The **connectedUsersMetrics** dataset lets you get real-time aggregated data, provided by Azion Live Ingest, related to the number of users connected to your applications with live streamings. This dataset is part of the Real-Time Metrics GraphQL API.

This information can be accessed through the GraphQL API, allowing you to transfer this data to a third-party platform, and enabling you to further analysis and review of user activity and engagement. Additionally, the data is available for up to *2 years*.

This guide will explain how to query Connected Users data using the GraphiQL playground.

:::note
To retrieve this data, you must be subscribed to [Azion Live Ingest](https://www.azion.com/en/solutions/live-streaming-delivery/) and use the [GraphQL API](/en/documentation/devtools/graphql-api/overview/).
:::

---

## Querying data by host

To query your data by host, proceed as follows:

1. Access the GraphiQL Playground by going to the following link: `https://api.azion.com/v4/metrics/graphql`.
    - You must be logged in to your Azion account. Otherwise, you'll receive an error message.
2. Send a query following this format:

```bash
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
    }
}
```

Where:

| Field | Description |
|----------|----------|
| `limit` | Specifies the maximum number of results to return. System maximum: `10000` |
| `filter` | Defines the criteria used to filter the data returned by the query |
| `tsRange` | A subfield of `filter`. Specifies a time range for filtering data. It includes `begin` and `end` fields to define the start and end timestamps. Format: `"YYYY-MM-DDTHH:mm:ss"`; example: `"2024-04-11T00:00:00"` |
| `groupBy` | Specifies the fields by which the query results should be grouped. Example: `[ts]` |
| `orderBy` | Specifies the order in which the results should be returned. Examples: `[ts_DESC]`, for descending order, and `[ts_ASC]`, for ascending order |
| `ts` | A field in the result set representing the timestamp of the data point |
| `host` | A field in the result set representing the host from which the data was collected |
| `uniqueSessions` | A field in the result set representing the number of unique sessions recorded by the host |

3. You'll receive a JSON response similar to this: 

```bash
{
  "data": {
    "connectedUsersMetrics": [
      {
        "ts": "2024-04-10T00:00:00",
  "host": "example.net",
        "uniqueSessions": 120
      },
      {
        "ts": "2024-04-10T00:00:00",
  "host": "example.net",
        "uniqueSessions": 175
      },
      {
        "ts": "2024-04-10T00:00:00",
  "host": "example.net",
        "uniqueSessions": 136
      },
      {
        "ts": "2024-04-10T00:00:00",
  "host": "example.net",
        "uniqueSessions": 100
      }
    ]
  }
}
```

Where: 

| Field | Description |
|----------|----------|
| `ts` | Timestamp of when the event was created |
| `host` | Host information sent on the request line. Stores: hostname from the request line, or hostname from the “Host” request header field, or the server name matching a request |
| `uniqueSessions` | Unique sessions calculated for a given host |

---

## Querying total data

To retrieve total values, without filtering by host, you must use the field `uniqueSessionsTotal`:

1. Access the GraphiQL Playground by following this link: `https://api.azion.com/v4/metrics/graphql`
    - You must be logged in to your Azion account. Otherwise, you'll receive an error message.
2. Send a query following this format:

```bash
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
    }
}
```

Where:

| Field | Description |
|----------|----------|
| `limit` | Specifies the maximum number of results to return. System maximum: `10000` |
| `filter` | Defines the criteria used to filter the data returned by the query |
| `tsRange` | A subfield of `filter`. Specifies a time range for filtering data. It includes `begin` and `end` fields to define the start and end timestamps. Format: `"YYYY-MM-DDTHH:mm:ss"`; example: `"2024-04-11T00:00:00"` |
| `groupBy` | Specifies the fields by which the query results should be grouped. Example: `[ts,host]` |
| `orderBy` | Specifies the order in which the results should be returned. Accepted values: `[ts_DESC]`, for descending order, and `[ts_ASC]`, for ascending order |
| `ts` | A field in the result set representing the timestamp of the data point |
| `uniqueSessionsTotal` | A field in the result set representing the number of unique sessions recorded across all hosts for the specified time range |

3. You'll receive a JSON response similar to this: 

```bash
{
  "data": {
    "connectedUsersMetrics": [
      {
        "ts": "2024-04-10T00:00:00",
        "uniqueSessionsTotal": 169
      },
      {
        "ts": "2024-04-10T00:00:00",
        "uniqueSessionsTotal": 175
      },
      {
        "ts": "2024-04-10T00:00:00",
        "uniqueSessionsTotal": 120
      },
      {
        "ts": "2024-04-10T00:00:00",
        "uniqueSessionsTotal": 100
      }
    ]
  }
}
```

Where: 

| Field | Description |
|----------|----------|
| `ts` | Timestamp of when the event was created |
| `uniqueSessionsTotal` | Total unique sessions calculated among all hosts |