Skip to content
Ona API Reference
Ona Docs
API Reference
Usage

GetAgentTraceTimeSeries

usage.get_agent_trace_time_series(UsageGetAgentTraceTimeSeriesParams**kwargs) -> 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

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

Date range to query 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 scope results.

resolution: Optional[Resolution]

Time resolution for the series data.

One of the following:
"RESOLUTION_UNSPECIFIED"
"RESOLUTION_HOURLY"
"RESOLUTION_DAILY"
"RESOLUTION_WEEKLY"
"RESOLUTION_MONTHLY"
team_id: Optional[str]

Optional team ID to scope results to a specific team. Mutually exclusive with user_id.

user_id: Optional[str]

Optional user ID to scope results to a specific user. Mutually exclusive with team_id.

ReturnsExpand Collapse
class UsageGetAgentTraceTimeSeriesResponse: …
time_series: Optional[List[AgentTraceTimeBucket]]

Time series of agent trace stats, bucketed by the requested resolution.

by_model: Optional[List[AgentTraceModelBreakdown]]

Per-model breakdown for this bucket.

lines_added: Optional[str]

Lines added by sessions using this model.

lines_removed: Optional[str]

Lines removed by sessions using this model.

model: Optional[SupportedModel]

The model these stats are for.

One of the following:
"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: Optional[str]

Number of sessions that used this model.

start_time: Optional[datetime]

Start of this time bucket.

formatdate-time
total_lines_added: Optional[str]

Total lines added in this bucket.

total_lines_removed: Optional[str]

Total lines removed in this bucket.

total_sessions: Optional[str]

Number of agent trace sessions in this bucket.

GetAgentTraceTimeSeries

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_agent_trace_time_series(
    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",
    resolution="RESOLUTION_WEEKLY",
)
print(response.time_series)
{
  "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"
    }
  ]
}
Returns Examples
{
  "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"
    }
  ]
}