Skip to content
Ona API Reference
Ona Docs
API Reference
Usage

GetAgentTraceSummary

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

dateRange:
  startTime: "2024-01-01T00:00:00Z"
  endTime: "2024-02-01T00:00:00Z"
projectId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
Body ParametersJSONExpand Collapse
dateRange: DateRange { endTime, startTime }

Date range to query within.

endTime: string

End time of the date range (exclusive).

formatdate-time
startTime: string

Start time of the date range (inclusive).

formatdate-time
projectId: optional string

Optional project ID to scope results.

teamId: optional string

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

userId: optional string

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

ReturnsExpand Collapse
sparkline: optional array of TimeSeriesPoint { time, value }

Sparkline data for card rendering.

time: optional string

Timestamp for this data point.

formatdate-time
value: optional number

The numerical value for this data point.

formatint32
summary: optional AgentTraceSummary { byModel, totalLinesAdded, totalLinesAddedTrend, 4 more }

Summary totals and trends for the requested date range.

byModel: optional array of AgentTraceModelBreakdown { linesAdded, linesRemoved, model, sessions }

Per-model breakdown of session stats.

linesAdded: optional string

Lines added by sessions using this model.

linesRemoved: optional string

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 string

Number of sessions that used this model.

totalLinesAdded: optional string

Total lines added across all sessions.

totalLinesAddedTrend: optional number

Fractional change in total_lines_added compared to the previous period.

formatdouble
totalLinesRemoved: optional string

Total lines removed across all sessions.

totalLinesRemovedTrend: optional number

Fractional change in total_lines_removed compared to the previous period.

formatdouble
totalSessions: optional string

Total number of agent trace sessions in the date range.

totalSessionsTrend: optional 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.

formatdouble

GetAgentTraceSummary

curl https://app.gitpod.io/api/gitpod.v1.UsageService/GetAgentTraceSummary \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "dateRange": {
            "endTime": "2024-02-01T00:00:00Z",
            "startTime": "2024-01-01T00:00:00Z"
          }
        }'
{
  "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
  }
}
Returns Examples
{
  "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
  }
}