Skip to content
Ona API Reference
Ona Docs
API Reference
Usage

GetAdoptionUsageSummary

usage.get_adoption_usage_summary(UsageGetAdoptionUsageSummaryParams**kwargs) -> UsageGetAdoptionUsageSummaryResponse
POST/gitpod.v1.UsageService/GetAdoptionUsageSummary

Gets a summary of adoption and usage metrics.

Returns all scalar values, trends, and a sparkline for the Adoption & Usage insight category. For full-resolution time series, use the individual time series RPCs.

Use this method to:

  • Build adoption and usage insight cards
  • Filter adoption metrics by project, user, or team
  • Compare the requested date range against the previous period

Example

dateRange:
  startTime: "2024-01-01T00:00:00Z"
  endTime: "2024-02-01T00:00:00Z"
projectId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
ParametersExpand Collapse
date_range: DateRange

Date range to query metrics within.

end_time: datetime

End time of the date range (exclusive).

formatdate-time
start_time: datetime

Start time of the date range (inclusive).

formatdate-time
project_id: Optional[str]

Optional project ID to filter metrics by.

team_id: Optional[str]

Optional team ID to scope results to members of a specific team.

user_id: Optional[str]

Optional user ID to filter metrics for a specific user (personal insights view).

ReturnsExpand Collapse
class UsageGetAdoptionUsageSummaryResponse: …
active_users_count: Optional[str]

Count of active users in the date range.

active_users_trend: Optional[float]

Fractional change in active_users_count vs previous period. Computed as (current - previous) / previous.

formatdouble
env_runtime_per_user_seconds: Optional[float]

Average environment runtime in seconds per active user.

formatdouble
env_runtime_per_user_trend: Optional[float]

Fractional change in env_runtime_per_user_seconds vs previous period. Computed as (current - previous) / previous.

formatdouble
power_users_count: Optional[str]

Count of power users in the date range.

power_users_threshold_seconds: Optional[str]

Threshold in seconds used to determine power users. Displayed to users so they understand the definition.

power_users_trend: Optional[float]

Fractional change in power_users_count vs previous period. Computed as (current - previous) / previous.

formatdouble
sessions_count: Optional[str]

Count of environment sessions (total starts) in the date range.

sessions_trend: Optional[float]

Fractional change in sessions_count vs previous period. Computed as (current - previous) / previous.

formatdouble
sparkline: Optional[List[TimeSeriesPoint]]

Sparkline data for the card’s trend line (typically ~4 weekly points).

time: Optional[datetime]

Timestamp for this data point.

formatdate-time
value: Optional[int]

The numerical value for this data point.

formatint32

GetAdoptionUsageSummary

import os
from datetime import datetime
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
response = client.usage.get_adoption_usage_summary(
    date_range={
        "end_time": datetime.fromisoformat("2024-02-01T00:00:00"),
        "start_time": datetime.fromisoformat("2024-01-01T00:00:00"),
    },
    project_id="d2c94c27-3b76-4a42-b88c-95a85e392c68",
)
print(response.active_users_count)
{
  "activeUsersCount": "activeUsersCount",
  "activeUsersTrend": 0,
  "envRuntimePerUserSeconds": 0,
  "envRuntimePerUserTrend": 0,
  "powerUsersCount": "powerUsersCount",
  "powerUsersThresholdSeconds": "powerUsersThresholdSeconds",
  "powerUsersTrend": 0,
  "sessionsCount": "sessionsCount",
  "sessionsTrend": 0,
  "sparkline": [
    {
      "time": "2019-12-27T18:11:19.117Z",
      "value": 0
    }
  ]
}
Returns Examples
{
  "activeUsersCount": "activeUsersCount",
  "activeUsersTrend": 0,
  "envRuntimePerUserSeconds": 0,
  "envRuntimePerUserTrend": 0,
  "powerUsersCount": "powerUsersCount",
  "powerUsersThresholdSeconds": "powerUsersThresholdSeconds",
  "powerUsersTrend": 0,
  "sessionsCount": "sessionsCount",
  "sessionsTrend": 0,
  "sparkline": [
    {
      "time": "2019-12-27T18:11:19.117Z",
      "value": 0
    }
  ]
}