# Usage ## GetAdoptionUsageSummary `client.usage.getAdoptionUsageSummary(UsageGetAdoptionUsageSummaryParamsbody, RequestOptionsoptions?): 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 ```yaml dateRange: startTime: "2024-01-01T00:00:00Z" endTime: "2024-02-01T00:00:00Z" projectId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `body: UsageGetAdoptionUsageSummaryParams` - `dateRange: DateRange` Date range to query metrics within. - `endTime: string` End time of the date range (exclusive). - `startTime: string` Start time of the date range (inclusive). - `projectId?: string` Optional project ID to filter metrics by. - `teamId?: string` Optional team ID to scope results to members of a specific team. - `userId?: string` Optional user ID to filter metrics for a specific user (personal insights view). ### Returns - `UsageGetAdoptionUsageSummaryResponse` - `activeUsersCount?: string` Count of active users in the date range. - `activeUsersTrend?: number` Fractional change in active_users_count vs previous period. Computed as (current - previous) / previous. - `envRuntimePerUserSeconds?: number` Average environment runtime in seconds per active user. - `envRuntimePerUserTrend?: number` Fractional change in env_runtime_per_user_seconds vs previous period. Computed as (current - previous) / previous. - `powerUsersCount?: string` Count of power users in the date range. - `powerUsersThresholdSeconds?: string` Threshold in seconds used to determine power users. Displayed to users so they understand the definition. - `powerUsersTrend?: number` Fractional change in power_users_count vs previous period. Computed as (current - previous) / previous. - `sessionsCount?: string` Count of environment sessions (total starts) in the date range. - `sessionsTrend?: number` Fractional change in sessions_count vs previous period. Computed as (current - previous) / previous. - `sparkline?: Array` Sparkline data for the card's trend line (typically ~4 weekly points). - `time?: string` Timestamp for this data point. - `value?: number` The numerical value for this data point. ### Example ```typescript import Gitpod from '@gitpod/sdk'; const client = new Gitpod({ bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted }); const response = await client.usage.getAdoptionUsageSummary({ dateRange: { endTime: '2024-02-01T00:00:00Z', startTime: '2024-01-01T00:00:00Z' }, projectId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68', }); console.log(response.activeUsersCount); ``` #### Response ```json { "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 } ] } ``` ## GetAgentTraceSummary `client.usage.getAgentTraceSummary(UsageGetAgentTraceSummaryParamsbody, RequestOptionsoptions?): UsageGetAgentTraceSummaryResponse` **post** `/gitpod.v1.UsageService/GetAgentTraceSummary` Gets aggregated agent trace summary for the organization or a specific project. Use this method to: - Measure agent sessions and line changes - Break down agent activity by model - Scope agent trace insights to a project, user, or team ### Example ```yaml dateRange: startTime: "2024-01-01T00:00:00Z" endTime: "2024-02-01T00:00:00Z" projectId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `body: UsageGetAgentTraceSummaryParams` - `dateRange: DateRange` Date range to query within. - `endTime: string` End time of the date range (exclusive). - `startTime: string` Start time of the date range (inclusive). - `projectId?: string` Optional project ID to scope results. - `teamId?: string` Optional team ID to scope results to a specific team. Mutually exclusive with user_id. - `userId?: string` Optional user ID to scope results to a specific user. Mutually exclusive with team_id. ### Returns - `UsageGetAgentTraceSummaryResponse` - `sparkline?: Array` Sparkline data for card rendering. - `time?: string` Timestamp for this data point. - `value?: number` The numerical value for this data point. - `summary?: AgentTraceSummary` Summary totals and trends for the requested date range. - `byModel?: Array` Per-model breakdown of session stats. - `linesAdded?: string` Lines added by sessions using this model. - `linesRemoved?: string` Lines removed by sessions using this model. - `model?: SupportedModel` The model these stats are for. - `"SUPPORTED_MODEL_UNSPECIFIED"` - `"SUPPORTED_MODEL_SONNET_3_5"` - `"SUPPORTED_MODEL_SONNET_3_7"` - `"SUPPORTED_MODEL_SONNET_3_7_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4"` - `"SUPPORTED_MODEL_SONNET_4_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_5"` - `"SUPPORTED_MODEL_SONNET_4_5_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_6"` - `"SUPPORTED_MODEL_SONNET_4_6_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_5"` - `"SUPPORTED_MODEL_OPUS_4"` - `"SUPPORTED_MODEL_OPUS_4_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_5"` - `"SUPPORTED_MODEL_OPUS_4_5_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_6"` - `"SUPPORTED_MODEL_OPUS_4_6_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_7"` - `"SUPPORTED_MODEL_OPUS_4_8"` - `"SUPPORTED_MODEL_HAIKU_4_5"` - `"SUPPORTED_MODEL_OPENAI_4O"` - `"SUPPORTED_MODEL_OPENAI_4O_MINI"` - `"SUPPORTED_MODEL_OPENAI_O1"` - `"SUPPORTED_MODEL_OPENAI_O1_MINI"` - `"SUPPORTED_MODEL_OPENAI_AUTO"` - `sessions?: string` Number of sessions that used this model. - `totalLinesAdded?: string` Total lines added across all sessions. - `totalLinesAddedTrend?: number` Fractional change in total_lines_added compared to the previous period. - `totalLinesRemoved?: string` Total lines removed across all sessions. - `totalLinesRemovedTrend?: number` Fractional change in total_lines_removed compared to the previous period. - `totalSessions?: string` Total number of agent trace sessions in the date range. - `totalSessionsTrend?: number` Fractional change in total_sessions compared to the previous period of equal length. Computed as (current - previous) / previous. Zero when there is no previous data. ### Example ```typescript import Gitpod from '@gitpod/sdk'; const client = new Gitpod({ bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted }); const response = await client.usage.getAgentTraceSummary({ dateRange: { endTime: '2024-02-01T00:00:00Z', startTime: '2024-01-01T00:00:00Z' }, projectId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68', }); console.log(response.sparkline); ``` #### Response ```json { "sparkline": [ { "time": "2019-12-27T18:11:19.117Z", "value": 0 } ], "summary": { "byModel": [ { "linesAdded": "linesAdded", "linesRemoved": "linesRemoved", "model": "SUPPORTED_MODEL_UNSPECIFIED", "sessions": "sessions" } ], "totalLinesAdded": "totalLinesAdded", "totalLinesAddedTrend": 0, "totalLinesRemoved": "totalLinesRemoved", "totalLinesRemovedTrend": 0, "totalSessions": "totalSessions", "totalSessionsTrend": 0 } } ``` ## GetAgentTraceTimeSeries `client.usage.getAgentTraceTimeSeries(UsageGetAgentTraceTimeSeriesParamsbody, RequestOptionsoptions?): UsageGetAgentTraceTimeSeriesResponse` **post** `/gitpod.v1.UsageService/GetAgentTraceTimeSeries` Gets agent trace data as a time series. Use this method to: - Chart agent sessions and line changes over time - Select hourly, daily, weekly, or monthly buckets - Scope agent trace insights to a project, user, or team ### Example ```yaml dateRange: startTime: "2024-01-01T00:00:00Z" endTime: "2024-02-01T00:00:00Z" resolution: RESOLUTION_WEEKLY projectId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `body: UsageGetAgentTraceTimeSeriesParams` - `dateRange: DateRange` Date range to query within. - `endTime: string` End time of the date range (exclusive). - `startTime: string` Start time of the date range (inclusive). - `projectId?: string` Optional project ID to scope results. - `resolution?: Resolution` Time resolution for the series data. - `"RESOLUTION_UNSPECIFIED"` - `"RESOLUTION_HOURLY"` - `"RESOLUTION_DAILY"` - `"RESOLUTION_WEEKLY"` - `"RESOLUTION_MONTHLY"` - `teamId?: string` Optional team ID to scope results to a specific team. Mutually exclusive with user_id. - `userId?: string` Optional user ID to scope results to a specific user. Mutually exclusive with team_id. ### Returns - `UsageGetAgentTraceTimeSeriesResponse` - `timeSeries?: Array` Time series of agent trace stats, bucketed by the requested resolution. - `byModel?: Array` Per-model breakdown for this bucket. - `linesAdded?: string` Lines added by sessions using this model. - `linesRemoved?: string` Lines removed by sessions using this model. - `model?: SupportedModel` The model these stats are for. - `"SUPPORTED_MODEL_UNSPECIFIED"` - `"SUPPORTED_MODEL_SONNET_3_5"` - `"SUPPORTED_MODEL_SONNET_3_7"` - `"SUPPORTED_MODEL_SONNET_3_7_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4"` - `"SUPPORTED_MODEL_SONNET_4_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_5"` - `"SUPPORTED_MODEL_SONNET_4_5_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_6"` - `"SUPPORTED_MODEL_SONNET_4_6_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_5"` - `"SUPPORTED_MODEL_OPUS_4"` - `"SUPPORTED_MODEL_OPUS_4_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_5"` - `"SUPPORTED_MODEL_OPUS_4_5_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_6"` - `"SUPPORTED_MODEL_OPUS_4_6_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_7"` - `"SUPPORTED_MODEL_OPUS_4_8"` - `"SUPPORTED_MODEL_HAIKU_4_5"` - `"SUPPORTED_MODEL_OPENAI_4O"` - `"SUPPORTED_MODEL_OPENAI_4O_MINI"` - `"SUPPORTED_MODEL_OPENAI_O1"` - `"SUPPORTED_MODEL_OPENAI_O1_MINI"` - `"SUPPORTED_MODEL_OPENAI_AUTO"` - `sessions?: string` Number of sessions that used this model. - `startTime?: string` Start of this time bucket. - `totalLinesAdded?: string` Total lines added in this bucket. - `totalLinesRemoved?: string` Total lines removed in this bucket. - `totalSessions?: string` Number of agent trace sessions in this bucket. ### Example ```typescript import Gitpod from '@gitpod/sdk'; const client = new Gitpod({ bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted }); const response = await client.usage.getAgentTraceTimeSeries({ dateRange: { endTime: '2024-02-01T00:00:00Z', startTime: '2024-01-01T00:00:00Z' }, projectId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68', resolution: 'RESOLUTION_WEEKLY', }); console.log(response.timeSeries); ``` #### Response ```json { "timeSeries": [ { "byModel": [ { "linesAdded": "linesAdded", "linesRemoved": "linesRemoved", "model": "SUPPORTED_MODEL_UNSPECIFIED", "sessions": "sessions" } ], "startTime": "2019-12-27T18:11:19.117Z", "totalLinesAdded": "totalLinesAdded", "totalLinesRemoved": "totalLinesRemoved", "totalSessions": "totalSessions" } ] } ``` ## GetCoAuthorSummary `client.usage.getCoAuthorSummary(UsageGetCoAuthorSummaryParamsbody, RequestOptionsoptions?): UsageGetCoAuthorSummaryResponse` **post** `/gitpod.v1.UsageService/GetCoAuthorSummary` Gets aggregated co-author summary for the organization or a specific project. Use this method to: - Measure AI-assisted commits and line changes - Scope co-author insights to a project, user, or team - Compare the requested date range against the previous period ### Example ```yaml dateRange: startTime: "2024-01-01T00:00:00Z" endTime: "2024-02-01T00:00:00Z" projectId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `body: UsageGetCoAuthorSummaryParams` - `dateRange: DateRange` Date range to query within. - `endTime: string` End time of the date range (exclusive). - `startTime: string` Start time of the date range (inclusive). - `projectId?: string` Optional project ID to scope results. - `teamId?: string` Optional team ID to scope results to a specific team. Mutually exclusive with user_id. - `userId?: string` Optional user ID to scope results to a specific user. Mutually exclusive with team_id. ### Returns - `UsageGetCoAuthorSummaryResponse` - `sparkline?: Array` Sparkline data for card rendering. - `time?: string` Timestamp for this data point. - `value?: number` The numerical value for this data point. - `summary?: CoAuthorSummary` Summary totals and trends for the requested date range. - `byTool?: Array` Per-tool breakdown of contribution stats. - `commits?: string` Number of commits attributed to this tool. - `distinctAuthors?: string` Distinct authors who used this tool. - `linesAdded?: string` Lines added by this tool. - `linesRemoved?: string` Lines removed by this tool. - `tool?: CoAuthorTool` The tool these stats are for. - `"CO_AUTHOR_TOOL_UNSPECIFIED"` - `"CO_AUTHOR_TOOL_NO_COAUTHOR"` - `"CO_AUTHOR_TOOL_HUMAN_COAUTHOR"` - `"CO_AUTHOR_TOOL_ONA"` - `"CO_AUTHOR_TOOL_GITHUB_COPILOT"` - `"CO_AUTHOR_TOOL_CURSOR"` - `"CO_AUTHOR_TOOL_OTHER"` - `"CO_AUTHOR_TOOL_CLAUDE"` - `"CO_AUTHOR_TOOL_CODEX"` - `distinctAuthors?: string` Number of distinct authors (by author_hash). - `distinctAuthorsTrend?: number` Fractional change in distinct_authors compared to the previous period. - `totalCommits?: string` Total number of commits in the date range. - `totalCommitsTrend?: number` Fractional change in total_commits compared to the previous period of equal length. Computed as (current - previous) / previous. Zero when there is no previous data. - `totalLinesAdded?: string` Total lines added across all commits. - `totalLinesAddedTrend?: number` Fractional change in total_lines_added compared to the previous period. - `totalLinesRemoved?: string` Total lines removed across all commits. - `totalLinesRemovedTrend?: number` Fractional change in total_lines_removed compared to the previous period. ### Example ```typescript import Gitpod from '@gitpod/sdk'; const client = new Gitpod({ bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted }); const response = await client.usage.getCoAuthorSummary({ dateRange: { endTime: '2024-02-01T00:00:00Z', startTime: '2024-01-01T00:00:00Z' }, projectId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68', }); console.log(response.sparkline); ``` #### Response ```json { "sparkline": [ { "time": "2019-12-27T18:11:19.117Z", "value": 0 } ], "summary": { "byTool": [ { "commits": "commits", "distinctAuthors": "distinctAuthors", "linesAdded": "linesAdded", "linesRemoved": "linesRemoved", "tool": "CO_AUTHOR_TOOL_UNSPECIFIED" } ], "distinctAuthors": "distinctAuthors", "distinctAuthorsTrend": 0, "totalCommits": "totalCommits", "totalCommitsTrend": 0, "totalLinesAdded": "totalLinesAdded", "totalLinesAddedTrend": 0, "totalLinesRemoved": "totalLinesRemoved", "totalLinesRemovedTrend": 0 } } ``` ## GetCoAuthorTimeSeries `client.usage.getCoAuthorTimeSeries(UsageGetCoAuthorTimeSeriesParamsbody, RequestOptionsoptions?): UsageGetCoAuthorTimeSeriesResponse` **post** `/gitpod.v1.UsageService/GetCoAuthorTimeSeries` Gets co-author contribution data as a time series. Use this method to: - Chart AI-assisted commits and line changes over time - Select hourly, daily, weekly, or monthly buckets - Scope co-author insights to a project, user, or team ### Example ```yaml dateRange: startTime: "2024-01-01T00:00:00Z" endTime: "2024-02-01T00:00:00Z" resolution: RESOLUTION_WEEKLY projectId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `body: UsageGetCoAuthorTimeSeriesParams` - `dateRange: DateRange` Date range to query within. - `endTime: string` End time of the date range (exclusive). - `startTime: string` Start time of the date range (inclusive). - `projectId?: string` Optional project ID to scope results. - `resolution?: Resolution` Time resolution for the series data. - `"RESOLUTION_UNSPECIFIED"` - `"RESOLUTION_HOURLY"` - `"RESOLUTION_DAILY"` - `"RESOLUTION_WEEKLY"` - `"RESOLUTION_MONTHLY"` - `teamId?: string` Optional team ID to scope results to a specific team. Mutually exclusive with user_id. - `userId?: string` Optional user ID to scope results to a specific user. Mutually exclusive with team_id. ### Returns - `UsageGetCoAuthorTimeSeriesResponse` - `timeSeries?: Array` Time series of contribution stats, bucketed by the requested resolution. - `aiRatio?: number` Ratio of AI-assisted lines added to total lines added (0.0–1.0). - `byTool?: Array` Per-tool breakdown for this bucket. - `commits?: string` Number of commits attributed to this tool. - `distinctAuthors?: string` Distinct authors who used this tool. - `linesAdded?: string` Lines added by this tool. - `linesRemoved?: string` Lines removed by this tool. - `tool?: CoAuthorTool` The tool these stats are for. - `"CO_AUTHOR_TOOL_UNSPECIFIED"` - `"CO_AUTHOR_TOOL_NO_COAUTHOR"` - `"CO_AUTHOR_TOOL_HUMAN_COAUTHOR"` - `"CO_AUTHOR_TOOL_ONA"` - `"CO_AUTHOR_TOOL_GITHUB_COPILOT"` - `"CO_AUTHOR_TOOL_CURSOR"` - `"CO_AUTHOR_TOOL_OTHER"` - `"CO_AUTHOR_TOOL_CLAUDE"` - `"CO_AUTHOR_TOOL_CODEX"` - `distinctAuthors?: string` Number of distinct authors (by author_hash) in this bucket. - `startTime?: string` Start of this time bucket. - `totalCommits?: string` Total number of commits in this bucket (across all tools). - `totalLinesAdded?: string` Total lines added in this bucket (across all tools). - `totalLinesRemoved?: string` Total lines removed in this bucket (across all tools). ### Example ```typescript import Gitpod from '@gitpod/sdk'; const client = new Gitpod({ bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted }); const response = await client.usage.getCoAuthorTimeSeries({ dateRange: { endTime: '2024-02-01T00:00:00Z', startTime: '2024-01-01T00:00:00Z' }, projectId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68', resolution: 'RESOLUTION_WEEKLY', }); console.log(response.timeSeries); ``` #### Response ```json { "timeSeries": [ { "aiRatio": 0, "byTool": [ { "commits": "commits", "distinctAuthors": "distinctAuthors", "linesAdded": "linesAdded", "linesRemoved": "linesRemoved", "tool": "CO_AUTHOR_TOOL_UNSPECIFIED" } ], "distinctAuthors": "distinctAuthors", "startTime": "2019-12-27T18:11:19.117Z", "totalCommits": "totalCommits", "totalLinesAdded": "totalLinesAdded", "totalLinesRemoved": "totalLinesRemoved" } ] } ``` ## GetPrSummary `client.usage.getPrSummary(UsageGetPrSummaryParamsbody, RequestOptionsoptions?): UsageGetPrSummaryResponse` **post** `/gitpod.v1.UsageService/GetPrSummary` Gets aggregated PR speed summary for the organization or a specific project. Use this method to: - Measure pull request lead time and review latency - Calculate deployment frequency from merged pull requests - Scope PR speed insights to a project, user, or team ### Example ```yaml dateRange: startTime: "2024-01-01T00:00:00Z" endTime: "2024-02-01T00:00:00Z" projectId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `body: UsageGetPrSummaryParams` - `dateRange: DateRange` Date range to query within. - `endTime: string` End time of the date range (exclusive). - `startTime: string` Start time of the date range (inclusive). - `projectId?: string` Optional project ID to scope results. - `teamId?: string` Optional team ID to scope results to a specific team. Mutually exclusive with user_id. - `userId?: string` Optional user ID to scope results to a specific user. Mutually exclusive with team_id. ### Returns - `UsageGetPrSummaryResponse` - `sparkline?: Array` Sparkline data for card rendering. - `time?: string` Timestamp for this data point. - `value?: number` The numerical value for this data point. - `summary?: PrSummary` Summary totals and trends for the requested date range. - `deploymentFrequency?: number` PRs merged to the default branch per week. - `deploymentFrequencyTrend?: number` Fractional change in deployment_frequency vs previous period. Computed as (current - previous) / previous. - `leadTimeSeconds?: number` Median lead time for changes in seconds (first commit → merge). - `leadTimeTrend?: number` Fractional change in lead_time_seconds vs previous period. Computed as (current - previous) / previous. - `prsMergedCount?: string` Total PRs merged in the date range. - `prsMergedTrend?: number` Fractional change in prs_merged_count vs previous period. Computed as (current - previous) / previous. - `timeToFirstApprovalSeconds?: number` Median time to first approval in seconds. Zero when no PRs in the range had approvals. - `timeToFirstApprovalTrend?: number` Fractional change in time_to_first_approval_seconds vs previous period. Computed as (current - previous) / previous. ### Example ```typescript import Gitpod from '@gitpod/sdk'; const client = new Gitpod({ bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted }); const response = await client.usage.getPrSummary({ dateRange: { endTime: '2024-02-01T00:00:00Z', startTime: '2024-01-01T00:00:00Z' }, projectId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68', }); console.log(response.sparkline); ``` #### Response ```json { "sparkline": [ { "time": "2019-12-27T18:11:19.117Z", "value": 0 } ], "summary": { "deploymentFrequency": 0, "deploymentFrequencyTrend": 0, "leadTimeSeconds": 0, "leadTimeTrend": 0, "prsMergedCount": "prsMergedCount", "prsMergedTrend": 0, "timeToFirstApprovalSeconds": 0, "timeToFirstApprovalTrend": 0 } } ``` ## GetPrTimeSeries `client.usage.getPrTimeSeries(UsageGetPrTimeSeriesParamsbody, RequestOptionsoptions?): UsageGetPrTimeSeriesResponse` **post** `/gitpod.v1.UsageService/GetPrTimeSeries` Gets PR speed metrics as a time series. Use this method to: - Chart pull request lead time, review latency, and deploy counts - Select hourly, daily, weekly, or monthly buckets - Scope PR speed insights to a project, user, or team ### Example ```yaml dateRange: startTime: "2024-01-01T00:00:00Z" endTime: "2024-02-01T00:00:00Z" resolution: RESOLUTION_WEEKLY projectId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `body: UsageGetPrTimeSeriesParams` - `dateRange: DateRange` Date range to query within. - `endTime: string` End time of the date range (exclusive). - `startTime: string` Start time of the date range (inclusive). - `projectId?: string` Optional project ID to scope results. - `resolution?: Resolution` Time resolution for the series data. - `"RESOLUTION_UNSPECIFIED"` - `"RESOLUTION_HOURLY"` - `"RESOLUTION_DAILY"` - `"RESOLUTION_WEEKLY"` - `"RESOLUTION_MONTHLY"` - `teamId?: string` Optional team ID to scope results to a specific team. Mutually exclusive with user_id. - `userId?: string` Optional user ID to scope results to a specific user. Mutually exclusive with team_id. ### Returns - `UsageGetPrTimeSeriesResponse` - `timeSeries?: Array` Time series of PR speed metrics, bucketed by the requested resolution. - `deploys?: string` Total number of deploys (merged PRs) in this bucket. - `leadTimeSeconds?: number` Median lead time in seconds for PRs merged in this bucket. - `prsMergedCount?: string` Number of PRs merged in this bucket. - `startTime?: string` Start of this time bucket. - `timeToFirstApprovalSeconds?: number` Median time to first approval in seconds for PRs in this bucket. Zero when no PRs in the bucket had approvals. ### Example ```typescript import Gitpod from '@gitpod/sdk'; const client = new Gitpod({ bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted }); const response = await client.usage.getPrTimeSeries({ dateRange: { endTime: '2024-02-01T00:00:00Z', startTime: '2024-01-01T00:00:00Z' }, projectId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68', resolution: 'RESOLUTION_WEEKLY', }); console.log(response.timeSeries); ``` #### Response ```json { "timeSeries": [ { "deploys": "deploys", "leadTimeSeconds": 0, "prsMergedCount": "prsMergedCount", "startTime": "2019-12-27T18:11:19.117Z", "timeToFirstApprovalSeconds": 0 } ] } ``` ## ListEnvironmentUsageRecords `client.usage.listEnvironmentRuntimeRecords(UsageListEnvironmentRuntimeRecordsParamsparams, RequestOptionsoptions?): RecordsPage` **post** `/gitpod.v1.UsageService/ListEnvironmentUsageRecords` Lists completed environment runtime records within a specified date range. Returns a list of environment runtime records that were completed within the specified date range. Records of currently running environments are not included. Use this method to: - View environment runtime records - Filter by project - Create custom usage reports ### Example ```yaml filter: projectId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" dateRange: startTime: "2024-01-01T00:00:00Z" endTime: "2024-01-02T00:00:00Z" pagination: pageSize: 100 ``` ### Parameters - `params: UsageListEnvironmentRuntimeRecordsParams` - `token?: string` Query param - `pageSize?: number` Query param - `filter?: Filter` Body param: Filter options. - `dateRange: DateRange` Date range to query runtime records within. - `endTime: string` End time of the date range (exclusive). - `startTime: string` Start time of the date range (inclusive). - `projectId?: string` Optional project ID to filter runtime records by. - `pagination?: Pagination` Body param: Pagination options. - `token?: string` Token for the next set of results that was returned as next_token of a PaginationResponse - `pageSize?: number` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `EnvironmentUsageRecord` EnvironmentUsageRecord represents a record of an environment from start to stop. - `id?: string` Environment usage record ID. - `createdAt?: string` Time when the environment was created. - `environmentClassId?: string` Environment class ID associated with the record. - `environmentId?: string` Environment ID associated with the record. - `projectId?: string` Project ID associated with the environment (if available). - `runnerId?: string` Runner ID associated with the environment. - `stoppedAt?: string` Time when the environment was stopped. - `userId?: string` User ID is the ID of the user who created the environment associated with the record. ### Example ```typescript import Gitpod from '@gitpod/sdk'; const client = new Gitpod({ bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const environmentUsageRecord of client.usage.listEnvironmentRuntimeRecords({ filter: { dateRange: { endTime: '2024-01-02T00:00:00Z', startTime: '2024-01-01T00:00:00Z' }, projectId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68', }, pagination: { pageSize: 100 }, })) { console.log(environmentUsageRecord.id); } ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "records": [ { "id": "id", "createdAt": "2019-12-27T18:11:19.117Z", "environmentClassId": "environmentClassId", "environmentId": "environmentId", "projectId": "projectId", "runnerId": "runnerId", "stoppedAt": "2019-12-27T18:11:19.117Z", "userId": "userId" } ] } ``` ## Domain Types ### Agent Trace Model Breakdown - `AgentTraceModelBreakdown` AgentTraceModelBreakdown contains stats for a single LLM model. - `linesAdded?: string` Lines added by sessions using this model. - `linesRemoved?: string` Lines removed by sessions using this model. - `model?: SupportedModel` The model these stats are for. - `"SUPPORTED_MODEL_UNSPECIFIED"` - `"SUPPORTED_MODEL_SONNET_3_5"` - `"SUPPORTED_MODEL_SONNET_3_7"` - `"SUPPORTED_MODEL_SONNET_3_7_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4"` - `"SUPPORTED_MODEL_SONNET_4_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_5"` - `"SUPPORTED_MODEL_SONNET_4_5_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_6"` - `"SUPPORTED_MODEL_SONNET_4_6_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_5"` - `"SUPPORTED_MODEL_OPUS_4"` - `"SUPPORTED_MODEL_OPUS_4_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_5"` - `"SUPPORTED_MODEL_OPUS_4_5_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_6"` - `"SUPPORTED_MODEL_OPUS_4_6_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_7"` - `"SUPPORTED_MODEL_OPUS_4_8"` - `"SUPPORTED_MODEL_HAIKU_4_5"` - `"SUPPORTED_MODEL_OPENAI_4O"` - `"SUPPORTED_MODEL_OPENAI_4O_MINI"` - `"SUPPORTED_MODEL_OPENAI_O1"` - `"SUPPORTED_MODEL_OPENAI_O1_MINI"` - `"SUPPORTED_MODEL_OPENAI_AUTO"` - `sessions?: string` Number of sessions that used this model. ### Agent Trace Summary - `AgentTraceSummary` AgentTraceSummary contains aggregate totals for a date range. - `byModel?: Array` Per-model breakdown of session stats. - `linesAdded?: string` Lines added by sessions using this model. - `linesRemoved?: string` Lines removed by sessions using this model. - `model?: SupportedModel` The model these stats are for. - `"SUPPORTED_MODEL_UNSPECIFIED"` - `"SUPPORTED_MODEL_SONNET_3_5"` - `"SUPPORTED_MODEL_SONNET_3_7"` - `"SUPPORTED_MODEL_SONNET_3_7_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4"` - `"SUPPORTED_MODEL_SONNET_4_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_5"` - `"SUPPORTED_MODEL_SONNET_4_5_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_6"` - `"SUPPORTED_MODEL_SONNET_4_6_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_5"` - `"SUPPORTED_MODEL_OPUS_4"` - `"SUPPORTED_MODEL_OPUS_4_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_5"` - `"SUPPORTED_MODEL_OPUS_4_5_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_6"` - `"SUPPORTED_MODEL_OPUS_4_6_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_7"` - `"SUPPORTED_MODEL_OPUS_4_8"` - `"SUPPORTED_MODEL_HAIKU_4_5"` - `"SUPPORTED_MODEL_OPENAI_4O"` - `"SUPPORTED_MODEL_OPENAI_4O_MINI"` - `"SUPPORTED_MODEL_OPENAI_O1"` - `"SUPPORTED_MODEL_OPENAI_O1_MINI"` - `"SUPPORTED_MODEL_OPENAI_AUTO"` - `sessions?: string` Number of sessions that used this model. - `totalLinesAdded?: string` Total lines added across all sessions. - `totalLinesAddedTrend?: number` Fractional change in total_lines_added compared to the previous period. - `totalLinesRemoved?: string` Total lines removed across all sessions. - `totalLinesRemovedTrend?: number` Fractional change in total_lines_removed compared to the previous period. - `totalSessions?: string` Total number of agent trace sessions in the date range. - `totalSessionsTrend?: number` Fractional change in total_sessions compared to the previous period of equal length. Computed as (current - previous) / previous. Zero when there is no previous data. ### Agent Trace Time Bucket - `AgentTraceTimeBucket` AgentTraceTimeBucket contains stats for a single time period. - `byModel?: Array` Per-model breakdown for this bucket. - `linesAdded?: string` Lines added by sessions using this model. - `linesRemoved?: string` Lines removed by sessions using this model. - `model?: SupportedModel` The model these stats are for. - `"SUPPORTED_MODEL_UNSPECIFIED"` - `"SUPPORTED_MODEL_SONNET_3_5"` - `"SUPPORTED_MODEL_SONNET_3_7"` - `"SUPPORTED_MODEL_SONNET_3_7_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4"` - `"SUPPORTED_MODEL_SONNET_4_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_5"` - `"SUPPORTED_MODEL_SONNET_4_5_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_6"` - `"SUPPORTED_MODEL_SONNET_4_6_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_5"` - `"SUPPORTED_MODEL_OPUS_4"` - `"SUPPORTED_MODEL_OPUS_4_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_5"` - `"SUPPORTED_MODEL_OPUS_4_5_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_6"` - `"SUPPORTED_MODEL_OPUS_4_6_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_7"` - `"SUPPORTED_MODEL_OPUS_4_8"` - `"SUPPORTED_MODEL_HAIKU_4_5"` - `"SUPPORTED_MODEL_OPENAI_4O"` - `"SUPPORTED_MODEL_OPENAI_4O_MINI"` - `"SUPPORTED_MODEL_OPENAI_O1"` - `"SUPPORTED_MODEL_OPENAI_O1_MINI"` - `"SUPPORTED_MODEL_OPENAI_AUTO"` - `sessions?: string` Number of sessions that used this model. - `startTime?: string` Start of this time bucket. - `totalLinesAdded?: string` Total lines added in this bucket. - `totalLinesRemoved?: string` Total lines removed in this bucket. - `totalSessions?: string` Number of agent trace sessions in this bucket. ### Co Author Summary - `CoAuthorSummary` CoAuthorSummary contains aggregate totals for a date range. - `byTool?: Array` Per-tool breakdown of contribution stats. - `commits?: string` Number of commits attributed to this tool. - `distinctAuthors?: string` Distinct authors who used this tool. - `linesAdded?: string` Lines added by this tool. - `linesRemoved?: string` Lines removed by this tool. - `tool?: CoAuthorTool` The tool these stats are for. - `"CO_AUTHOR_TOOL_UNSPECIFIED"` - `"CO_AUTHOR_TOOL_NO_COAUTHOR"` - `"CO_AUTHOR_TOOL_HUMAN_COAUTHOR"` - `"CO_AUTHOR_TOOL_ONA"` - `"CO_AUTHOR_TOOL_GITHUB_COPILOT"` - `"CO_AUTHOR_TOOL_CURSOR"` - `"CO_AUTHOR_TOOL_OTHER"` - `"CO_AUTHOR_TOOL_CLAUDE"` - `"CO_AUTHOR_TOOL_CODEX"` - `distinctAuthors?: string` Number of distinct authors (by author_hash). - `distinctAuthorsTrend?: number` Fractional change in distinct_authors compared to the previous period. - `totalCommits?: string` Total number of commits in the date range. - `totalCommitsTrend?: number` Fractional change in total_commits compared to the previous period of equal length. Computed as (current - previous) / previous. Zero when there is no previous data. - `totalLinesAdded?: string` Total lines added across all commits. - `totalLinesAddedTrend?: number` Fractional change in total_lines_added compared to the previous period. - `totalLinesRemoved?: string` Total lines removed across all commits. - `totalLinesRemovedTrend?: number` Fractional change in total_lines_removed compared to the previous period. ### Co Author Time Bucket - `CoAuthorTimeBucket` CoAuthorTimeBucket contains stats for a single time period. - `aiRatio?: number` Ratio of AI-assisted lines added to total lines added (0.0–1.0). - `byTool?: Array` Per-tool breakdown for this bucket. - `commits?: string` Number of commits attributed to this tool. - `distinctAuthors?: string` Distinct authors who used this tool. - `linesAdded?: string` Lines added by this tool. - `linesRemoved?: string` Lines removed by this tool. - `tool?: CoAuthorTool` The tool these stats are for. - `"CO_AUTHOR_TOOL_UNSPECIFIED"` - `"CO_AUTHOR_TOOL_NO_COAUTHOR"` - `"CO_AUTHOR_TOOL_HUMAN_COAUTHOR"` - `"CO_AUTHOR_TOOL_ONA"` - `"CO_AUTHOR_TOOL_GITHUB_COPILOT"` - `"CO_AUTHOR_TOOL_CURSOR"` - `"CO_AUTHOR_TOOL_OTHER"` - `"CO_AUTHOR_TOOL_CLAUDE"` - `"CO_AUTHOR_TOOL_CODEX"` - `distinctAuthors?: string` Number of distinct authors (by author_hash) in this bucket. - `startTime?: string` Start of this time bucket. - `totalCommits?: string` Total number of commits in this bucket (across all tools). - `totalLinesAdded?: string` Total lines added in this bucket (across all tools). - `totalLinesRemoved?: string` Total lines removed in this bucket (across all tools). ### Co Author Tool - `CoAuthorTool = "CO_AUTHOR_TOOL_UNSPECIFIED" | "CO_AUTHOR_TOOL_NO_COAUTHOR" | "CO_AUTHOR_TOOL_HUMAN_COAUTHOR" | 6 more` CoAuthorTool identifies the AI tool that co-authored a commit. UNSPECIFIED (0) is the proto default and must not appear in reported data. Use HUMAN for commits with no AI co-author. - `"CO_AUTHOR_TOOL_UNSPECIFIED"` - `"CO_AUTHOR_TOOL_NO_COAUTHOR"` - `"CO_AUTHOR_TOOL_HUMAN_COAUTHOR"` - `"CO_AUTHOR_TOOL_ONA"` - `"CO_AUTHOR_TOOL_GITHUB_COPILOT"` - `"CO_AUTHOR_TOOL_CURSOR"` - `"CO_AUTHOR_TOOL_OTHER"` - `"CO_AUTHOR_TOOL_CLAUDE"` - `"CO_AUTHOR_TOOL_CODEX"` ### Environment Usage Record - `EnvironmentUsageRecord` EnvironmentUsageRecord represents a record of an environment from start to stop. - `id?: string` Environment usage record ID. - `createdAt?: string` Time when the environment was created. - `environmentClassId?: string` Environment class ID associated with the record. - `environmentId?: string` Environment ID associated with the record. - `projectId?: string` Project ID associated with the environment (if available). - `runnerId?: string` Runner ID associated with the environment. - `stoppedAt?: string` Time when the environment was stopped. - `userId?: string` User ID is the ID of the user who created the environment associated with the record. ### Pr Summary - `PrSummary` PrSummary contains aggregate PR speed metrics for a date range. - `deploymentFrequency?: number` PRs merged to the default branch per week. - `deploymentFrequencyTrend?: number` Fractional change in deployment_frequency vs previous period. Computed as (current - previous) / previous. - `leadTimeSeconds?: number` Median lead time for changes in seconds (first commit → merge). - `leadTimeTrend?: number` Fractional change in lead_time_seconds vs previous period. Computed as (current - previous) / previous. - `prsMergedCount?: string` Total PRs merged in the date range. - `prsMergedTrend?: number` Fractional change in prs_merged_count vs previous period. Computed as (current - previous) / previous. - `timeToFirstApprovalSeconds?: number` Median time to first approval in seconds. Zero when no PRs in the range had approvals. - `timeToFirstApprovalTrend?: number` Fractional change in time_to_first_approval_seconds vs previous period. Computed as (current - previous) / previous. ### Pr Time Bucket - `PrTimeBucket` PrTimeBucket contains PR speed metrics for a single time period. - `deploys?: string` Total number of deploys (merged PRs) in this bucket. - `leadTimeSeconds?: number` Median lead time in seconds for PRs merged in this bucket. - `prsMergedCount?: string` Number of PRs merged in this bucket. - `startTime?: string` Start of this time bucket. - `timeToFirstApprovalSeconds?: number` Median time to first approval in seconds for PRs in this bucket. Zero when no PRs in the bucket had approvals. ### Resolution - `Resolution = "RESOLUTION_UNSPECIFIED" | "RESOLUTION_HOURLY" | "RESOLUTION_DAILY" | 2 more` Resolution specifies the time granularity for time series data. - `"RESOLUTION_UNSPECIFIED"` - `"RESOLUTION_HOURLY"` - `"RESOLUTION_DAILY"` - `"RESOLUTION_WEEKLY"` - `"RESOLUTION_MONTHLY"` ### Supported Model - `SupportedModel = "SUPPORTED_MODEL_UNSPECIFIED" | "SUPPORTED_MODEL_SONNET_3_5" | "SUPPORTED_MODEL_SONNET_3_7" | 22 more` SupportedModel enumerates the LLM models available for agent executions - `"SUPPORTED_MODEL_UNSPECIFIED"` - `"SUPPORTED_MODEL_SONNET_3_5"` - `"SUPPORTED_MODEL_SONNET_3_7"` - `"SUPPORTED_MODEL_SONNET_3_7_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4"` - `"SUPPORTED_MODEL_SONNET_4_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_5"` - `"SUPPORTED_MODEL_SONNET_4_5_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_6"` - `"SUPPORTED_MODEL_SONNET_4_6_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_5"` - `"SUPPORTED_MODEL_OPUS_4"` - `"SUPPORTED_MODEL_OPUS_4_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_5"` - `"SUPPORTED_MODEL_OPUS_4_5_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_6"` - `"SUPPORTED_MODEL_OPUS_4_6_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_7"` - `"SUPPORTED_MODEL_OPUS_4_8"` - `"SUPPORTED_MODEL_HAIKU_4_5"` - `"SUPPORTED_MODEL_OPENAI_4O"` - `"SUPPORTED_MODEL_OPENAI_4O_MINI"` - `"SUPPORTED_MODEL_OPENAI_O1"` - `"SUPPORTED_MODEL_OPENAI_O1_MINI"` - `"SUPPORTED_MODEL_OPENAI_AUTO"` ### Time Series Point - `TimeSeriesPoint` - `time?: string` Timestamp for this data point. - `value?: number` The numerical value for this data point. ### Tool Breakdown - `ToolBreakdown` ToolBreakdown contains stats for a single AI tool (or human). - `commits?: string` Number of commits attributed to this tool. - `distinctAuthors?: string` Distinct authors who used this tool. - `linesAdded?: string` Lines added by this tool. - `linesRemoved?: string` Lines removed by this tool. - `tool?: CoAuthorTool` The tool these stats are for. - `"CO_AUTHOR_TOOL_UNSPECIFIED"` - `"CO_AUTHOR_TOOL_NO_COAUTHOR"` - `"CO_AUTHOR_TOOL_HUMAN_COAUTHOR"` - `"CO_AUTHOR_TOOL_ONA"` - `"CO_AUTHOR_TOOL_GITHUB_COPILOT"` - `"CO_AUTHOR_TOOL_CURSOR"` - `"CO_AUTHOR_TOOL_OTHER"` - `"CO_AUTHOR_TOOL_CLAUDE"` - `"CO_AUTHOR_TOOL_CODEX"` ### Usage Get Adoption Usage Summary Response - `UsageGetAdoptionUsageSummaryResponse` - `activeUsersCount?: string` Count of active users in the date range. - `activeUsersTrend?: number` Fractional change in active_users_count vs previous period. Computed as (current - previous) / previous. - `envRuntimePerUserSeconds?: number` Average environment runtime in seconds per active user. - `envRuntimePerUserTrend?: number` Fractional change in env_runtime_per_user_seconds vs previous period. Computed as (current - previous) / previous. - `powerUsersCount?: string` Count of power users in the date range. - `powerUsersThresholdSeconds?: string` Threshold in seconds used to determine power users. Displayed to users so they understand the definition. - `powerUsersTrend?: number` Fractional change in power_users_count vs previous period. Computed as (current - previous) / previous. - `sessionsCount?: string` Count of environment sessions (total starts) in the date range. - `sessionsTrend?: number` Fractional change in sessions_count vs previous period. Computed as (current - previous) / previous. - `sparkline?: Array` Sparkline data for the card's trend line (typically ~4 weekly points). - `time?: string` Timestamp for this data point. - `value?: number` The numerical value for this data point. ### Usage Get Agent Trace Summary Response - `UsageGetAgentTraceSummaryResponse` - `sparkline?: Array` Sparkline data for card rendering. - `time?: string` Timestamp for this data point. - `value?: number` The numerical value for this data point. - `summary?: AgentTraceSummary` Summary totals and trends for the requested date range. - `byModel?: Array` Per-model breakdown of session stats. - `linesAdded?: string` Lines added by sessions using this model. - `linesRemoved?: string` Lines removed by sessions using this model. - `model?: SupportedModel` The model these stats are for. - `"SUPPORTED_MODEL_UNSPECIFIED"` - `"SUPPORTED_MODEL_SONNET_3_5"` - `"SUPPORTED_MODEL_SONNET_3_7"` - `"SUPPORTED_MODEL_SONNET_3_7_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4"` - `"SUPPORTED_MODEL_SONNET_4_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_5"` - `"SUPPORTED_MODEL_SONNET_4_5_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_6"` - `"SUPPORTED_MODEL_SONNET_4_6_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_5"` - `"SUPPORTED_MODEL_OPUS_4"` - `"SUPPORTED_MODEL_OPUS_4_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_5"` - `"SUPPORTED_MODEL_OPUS_4_5_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_6"` - `"SUPPORTED_MODEL_OPUS_4_6_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_7"` - `"SUPPORTED_MODEL_OPUS_4_8"` - `"SUPPORTED_MODEL_HAIKU_4_5"` - `"SUPPORTED_MODEL_OPENAI_4O"` - `"SUPPORTED_MODEL_OPENAI_4O_MINI"` - `"SUPPORTED_MODEL_OPENAI_O1"` - `"SUPPORTED_MODEL_OPENAI_O1_MINI"` - `"SUPPORTED_MODEL_OPENAI_AUTO"` - `sessions?: string` Number of sessions that used this model. - `totalLinesAdded?: string` Total lines added across all sessions. - `totalLinesAddedTrend?: number` Fractional change in total_lines_added compared to the previous period. - `totalLinesRemoved?: string` Total lines removed across all sessions. - `totalLinesRemovedTrend?: number` Fractional change in total_lines_removed compared to the previous period. - `totalSessions?: string` Total number of agent trace sessions in the date range. - `totalSessionsTrend?: number` Fractional change in total_sessions compared to the previous period of equal length. Computed as (current - previous) / previous. Zero when there is no previous data. ### Usage Get Agent Trace Time Series Response - `UsageGetAgentTraceTimeSeriesResponse` - `timeSeries?: Array` Time series of agent trace stats, bucketed by the requested resolution. - `byModel?: Array` Per-model breakdown for this bucket. - `linesAdded?: string` Lines added by sessions using this model. - `linesRemoved?: string` Lines removed by sessions using this model. - `model?: SupportedModel` The model these stats are for. - `"SUPPORTED_MODEL_UNSPECIFIED"` - `"SUPPORTED_MODEL_SONNET_3_5"` - `"SUPPORTED_MODEL_SONNET_3_7"` - `"SUPPORTED_MODEL_SONNET_3_7_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4"` - `"SUPPORTED_MODEL_SONNET_4_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_5"` - `"SUPPORTED_MODEL_SONNET_4_5_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_4_6"` - `"SUPPORTED_MODEL_SONNET_4_6_EXTENDED"` - `"SUPPORTED_MODEL_SONNET_5"` - `"SUPPORTED_MODEL_OPUS_4"` - `"SUPPORTED_MODEL_OPUS_4_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_5"` - `"SUPPORTED_MODEL_OPUS_4_5_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_6"` - `"SUPPORTED_MODEL_OPUS_4_6_EXTENDED"` - `"SUPPORTED_MODEL_OPUS_4_7"` - `"SUPPORTED_MODEL_OPUS_4_8"` - `"SUPPORTED_MODEL_HAIKU_4_5"` - `"SUPPORTED_MODEL_OPENAI_4O"` - `"SUPPORTED_MODEL_OPENAI_4O_MINI"` - `"SUPPORTED_MODEL_OPENAI_O1"` - `"SUPPORTED_MODEL_OPENAI_O1_MINI"` - `"SUPPORTED_MODEL_OPENAI_AUTO"` - `sessions?: string` Number of sessions that used this model. - `startTime?: string` Start of this time bucket. - `totalLinesAdded?: string` Total lines added in this bucket. - `totalLinesRemoved?: string` Total lines removed in this bucket. - `totalSessions?: string` Number of agent trace sessions in this bucket. ### Usage Get Co Author Summary Response - `UsageGetCoAuthorSummaryResponse` - `sparkline?: Array` Sparkline data for card rendering. - `time?: string` Timestamp for this data point. - `value?: number` The numerical value for this data point. - `summary?: CoAuthorSummary` Summary totals and trends for the requested date range. - `byTool?: Array` Per-tool breakdown of contribution stats. - `commits?: string` Number of commits attributed to this tool. - `distinctAuthors?: string` Distinct authors who used this tool. - `linesAdded?: string` Lines added by this tool. - `linesRemoved?: string` Lines removed by this tool. - `tool?: CoAuthorTool` The tool these stats are for. - `"CO_AUTHOR_TOOL_UNSPECIFIED"` - `"CO_AUTHOR_TOOL_NO_COAUTHOR"` - `"CO_AUTHOR_TOOL_HUMAN_COAUTHOR"` - `"CO_AUTHOR_TOOL_ONA"` - `"CO_AUTHOR_TOOL_GITHUB_COPILOT"` - `"CO_AUTHOR_TOOL_CURSOR"` - `"CO_AUTHOR_TOOL_OTHER"` - `"CO_AUTHOR_TOOL_CLAUDE"` - `"CO_AUTHOR_TOOL_CODEX"` - `distinctAuthors?: string` Number of distinct authors (by author_hash). - `distinctAuthorsTrend?: number` Fractional change in distinct_authors compared to the previous period. - `totalCommits?: string` Total number of commits in the date range. - `totalCommitsTrend?: number` Fractional change in total_commits compared to the previous period of equal length. Computed as (current - previous) / previous. Zero when there is no previous data. - `totalLinesAdded?: string` Total lines added across all commits. - `totalLinesAddedTrend?: number` Fractional change in total_lines_added compared to the previous period. - `totalLinesRemoved?: string` Total lines removed across all commits. - `totalLinesRemovedTrend?: number` Fractional change in total_lines_removed compared to the previous period. ### Usage Get Co Author Time Series Response - `UsageGetCoAuthorTimeSeriesResponse` - `timeSeries?: Array` Time series of contribution stats, bucketed by the requested resolution. - `aiRatio?: number` Ratio of AI-assisted lines added to total lines added (0.0–1.0). - `byTool?: Array` Per-tool breakdown for this bucket. - `commits?: string` Number of commits attributed to this tool. - `distinctAuthors?: string` Distinct authors who used this tool. - `linesAdded?: string` Lines added by this tool. - `linesRemoved?: string` Lines removed by this tool. - `tool?: CoAuthorTool` The tool these stats are for. - `"CO_AUTHOR_TOOL_UNSPECIFIED"` - `"CO_AUTHOR_TOOL_NO_COAUTHOR"` - `"CO_AUTHOR_TOOL_HUMAN_COAUTHOR"` - `"CO_AUTHOR_TOOL_ONA"` - `"CO_AUTHOR_TOOL_GITHUB_COPILOT"` - `"CO_AUTHOR_TOOL_CURSOR"` - `"CO_AUTHOR_TOOL_OTHER"` - `"CO_AUTHOR_TOOL_CLAUDE"` - `"CO_AUTHOR_TOOL_CODEX"` - `distinctAuthors?: string` Number of distinct authors (by author_hash) in this bucket. - `startTime?: string` Start of this time bucket. - `totalCommits?: string` Total number of commits in this bucket (across all tools). - `totalLinesAdded?: string` Total lines added in this bucket (across all tools). - `totalLinesRemoved?: string` Total lines removed in this bucket (across all tools). ### Usage Get Pr Summary Response - `UsageGetPrSummaryResponse` - `sparkline?: Array` Sparkline data for card rendering. - `time?: string` Timestamp for this data point. - `value?: number` The numerical value for this data point. - `summary?: PrSummary` Summary totals and trends for the requested date range. - `deploymentFrequency?: number` PRs merged to the default branch per week. - `deploymentFrequencyTrend?: number` Fractional change in deployment_frequency vs previous period. Computed as (current - previous) / previous. - `leadTimeSeconds?: number` Median lead time for changes in seconds (first commit → merge). - `leadTimeTrend?: number` Fractional change in lead_time_seconds vs previous period. Computed as (current - previous) / previous. - `prsMergedCount?: string` Total PRs merged in the date range. - `prsMergedTrend?: number` Fractional change in prs_merged_count vs previous period. Computed as (current - previous) / previous. - `timeToFirstApprovalSeconds?: number` Median time to first approval in seconds. Zero when no PRs in the range had approvals. - `timeToFirstApprovalTrend?: number` Fractional change in time_to_first_approval_seconds vs previous period. Computed as (current - previous) / previous. ### Usage Get Pr Time Series Response - `UsageGetPrTimeSeriesResponse` - `timeSeries?: Array` Time series of PR speed metrics, bucketed by the requested resolution. - `deploys?: string` Total number of deploys (merged PRs) in this bucket. - `leadTimeSeconds?: number` Median lead time in seconds for PRs merged in this bucket. - `prsMergedCount?: string` Number of PRs merged in this bucket. - `startTime?: string` Start of this time bucket. - `timeToFirstApprovalSeconds?: number` Median time to first approval in seconds for PRs in this bucket. Zero when no PRs in the bucket had approvals.