> ## 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 Environment Sessions Time Series

> Gets the environment sessions time series in the specified date range, aggregated by the specified resolution.

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

Gets the environment sessions time series in the specified date range, aggregated by the specified resolution.

Environment sessions count total environment starts (environment.started events),
as opposed to GetActiveEnvironmentsTimeSeries which counts distinct environment IDs.

## Endpoint

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

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/GetEnvironmentSessionsTimeSeries" \
    --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.GetEnvironmentSessionsTimeSeriesRequest(
      date_range=usage_pb2.DateRange(
          start_time=timestamp_pb2.Timestamp(seconds=1767225600),
          end_time=timestamp_pb2.Timestamp(seconds=1767225600),
      ),
  )
  response = ona.services.usage.get_environment_sessions_time_series(request)
  print(response)
  ```

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

  async function main() {
    const ona = createClientFromEnv();
    const request = create(GetEnvironmentSessionsTimeSeriesRequestSchema, {
      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.getEnvironmentSessionsTimeSeries(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.GetEnvironmentSessionsTimeSeriesRequest{
  		DateRange: &gitpodpb.DateRange{
  			StartTime: &timestamppb.Timestamp{Seconds: 1767225600},
  			EndTime: &timestamppb.Timestamp{Seconds: 1767225600},
  		},
  	})
  	response, err := ona.Services.Usage.GetEnvironmentSessionsTimeSeries(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.GetEnvironmentSessionsTimeSeriesRequest`

| Field        | Type                                     | Required | Description                                                                 |
| ------------ | ---------------------------------------- | -------- | --------------------------------------------------------------------------- |
| `dateRange`  | [DateRange](#type-gitpod-v1-date-range)  | Yes      | Date range to query metrics within. Constraints: `required=true`.           |
| `projectId`  | string                                   | No       | Optional project ID to filter metrics by.                                   |
| `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.GetEnvironmentSessionsTimeSeriesResponse`

| Field      | Type                                                          | Required | Description                                                                                                                                                             |
| ---------- | ------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sessions` | array of [TimeSeriesPoint](#type-gitpod-v1-time-series-point) | No       | Environment sessions time series. Counts total environment starts per time bucket, as opposed to GetActiveEnvironmentsTimeSeries which counts distinct environment IDs. |

## 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>