> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Active Users Time Series

> Gets active users time series in the specified date range, aggregated by the specified resolution.

`Unary` · [`Usage`](/docs/api-reference/generated/usage/overview)

Gets active users time series in the specified date range, aggregated by the specified resolution.

Returns a time series of active user counts within the specified date range, aggregated by the specified resolution.
Each data point includes the timestamp and the count of unique users who were active at that time.

## Endpoint

```text theme={null}
POST /api/gitpod.v1.UsageService/GetActiveUsersTimeSeries
```

Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.

## Request example

<CodeGroup>
  ```bash cURL theme={null}
  export ONA_HOST=https://app.ona.com
  export ONA_API_KEY=<your-token>

  curl --request POST \
    --url "$ONA_HOST/api/gitpod.v1.UsageService/GetActiveUsersTimeSeries" \
    --header "Authorization: Bearer $ONA_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
    "dateRange": {
      "endTime": "2026-01-01T00:00:00Z",
      "startTime": "2026-01-01T00:00:00Z"
    }
  }'
  ```

  ```python Python theme={null}
  import gitpod.v1.usage_pb2 as usage_pb2
  import google.protobuf.timestamp_pb2 as timestamp_pb2
  from ona_sdk import create_client_from_env

  ona = create_client_from_env()
  request = usage_pb2.GetActiveUsersTimeSeriesRequest(
      date_range=usage_pb2.DateRange(
          start_time=timestamp_pb2.Timestamp(seconds=1767225600),
          end_time=timestamp_pb2.Timestamp(seconds=1767225600),
      ),
  )
  response = ona.services.usage.get_active_users_time_series(request)
  print(response)
  ```

  ```typescript TypeScript theme={null}
  import { create } from "@bufbuild/protobuf";
  import { createClientFromEnv } from "@gitpod/sdk";
  import { GetActiveUsersTimeSeriesRequestSchema } from "@gitpod/sdk/gitpod/v1/usage_pb";
  import { timestampFromDate } from "@bufbuild/protobuf/wkt";

  async function main() {
    const ona = createClientFromEnv();
    const request = create(GetActiveUsersTimeSeriesRequestSchema, {
      dateRange: {
        startTime: timestampFromDate(new Date("2026-01-01T00:00:00Z")),
        endTime: timestampFromDate(new Date("2026-01-01T00:00:00Z")),
      },
    });
    const response = await ona.services.usage.getActiveUsersTimeSeries(request);
    console.log(response);
  }

  main().catch(console.error);
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"log"

  	"connectrpc.com/connect"
  	"github.com/gitpod-io/gitpod-sdk-go/sdk"
  	gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
  	timestamppb "google.golang.org/protobuf/types/known/timestamppb"
  )

  func main() {
  	ona, err := sdk.NewFromEnv()
  	if err != nil {
  		log.Fatal(err)
  	}

  	request := connect.NewRequest(&gitpodpb.GetActiveUsersTimeSeriesRequest{
  		DateRange: &gitpodpb.DateRange{
  			StartTime: &timestamppb.Timestamp{Seconds: 1767225600},
  			EndTime: &timestamppb.Timestamp{Seconds: 1767225600},
  		},
  	})
  	response, err := ona.Services.Usage.GetActiveUsersTimeSeries(context.Background(), request)
  	if err != nil {
  		log.Fatal(err)
  	}
  	fmt.Println(response.Msg)
  }
  ```

  ```json Request body theme={null}
  {
    "dateRange": {
      "endTime": "2026-01-01T00:00:00Z",
      "startTime": "2026-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Request

`gitpod.v1.GetActiveUsersTimeSeriesRequest`

| Field        | Type                                     | Required | Description                                                                 |
| ------------ | ---------------------------------------- | -------- | --------------------------------------------------------------------------- |
| `projectId`  | string                                   | No       | Optional project ID to filter metrics by.                                   |
| `dateRange`  | [DateRange](#type-gitpod-v1-date-range)  | Yes      | Date range to query metrics within. Constraints: `required=true`.           |
| `resolution` | [Resolution](#enum-gitpod-v1-resolution) | No       | Time resolution for the series data. Constraints: `enum.defined_only=true`. |
| `teamId`     | string                                   | No       | Optional team ID to scope results to members of a specific team.            |

## Response

`gitpod.v1.GetActiveUsersTimeSeriesResponse`

| Field                        | Type                                                          | Required | Description                                        |
| ---------------------------- | ------------------------------------------------------------- | -------- | -------------------------------------------------- |
| `weeklyActiveUsers`          | array of [TimeSeriesPoint](#type-gitpod-v1-time-series-point) | No       | Weekly active users time series \[WAU]             |
| `weeklyActiveReturningUsers` | array of [TimeSeriesPoint](#type-gitpod-v1-time-series-point) | No       | Weekly active returning users time series \[WAU2+] |

## Related types

<a id="type-gitpod-v1-date-range" />

<Accordion title="DateRange">
  DateRange specifies a time period for queries.

  `gitpod.v1.DateRange`

  | Field       | Type               | Required | Description                                                             |
  | ----------- | ------------------ | -------- | ----------------------------------------------------------------------- |
  | `startTime` | RFC 3339 timestamp | Yes      | Start time of the date range (inclusive). Constraints: `required=true`. |
  | `endTime`   | RFC 3339 timestamp | Yes      | End time of the date range (exclusive). Constraints: `required=true`.   |
</Accordion>

<a id="type-gitpod-v1-time-series-point" />

<Accordion title="TimeSeriesPoint">
  `gitpod.v1.TimeSeriesPoint`

  | Field   | Type               | Required | Description                              |
  | ------- | ------------------ | -------- | ---------------------------------------- |
  | `time`  | RFC 3339 timestamp | No       | Timestamp for this data point.           |
  | `value` | integer            | No       | The numerical value for this data point. |
</Accordion>

<a id="enum-gitpod-v1-resolution" />

<Accordion title="Resolution">
  Resolution specifies the time granularity for time series data.

  | Value                    | Number | Description |
  | ------------------------ | -----: | ----------- |
  | `RESOLUTION_UNSPECIFIED` |      0 |             |
  | `RESOLUTION_HOURLY`      |      1 |             |
  | `RESOLUTION_DAILY`       |      2 |             |
  | `RESOLUTION_WEEKLY`      |      3 |             |
  | `RESOLUTION_MONTHLY`     |      4 |             |
</Accordion>