API Reference

Usage

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

GetAgentTraceSummary

client.Usage.GetAgentTraceSummary(ctx, body) (*UsageGetAgentTraceSummaryResponse, error)

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"

ParametersExpand Collapse

body UsageGetAgentTraceSummaryParams

DateRange param.Field[DateRange]

Date range to query within.

ProjectID param.Field[string]Optional

Optional project ID to scope results.

TeamID param.Field[string]Optional

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

UserID param.Field[string]Optional

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

ReturnsExpand Collapse

type UsageGetAgentTraceSummaryResponse struct{…}

Sparkline []TimeSeriesPointOptional

Sparkline data for card rendering.

Time TimeOptional

Timestamp for this data point.

formatdate-time

Value int64Optional

The numerical value for this data point.

formatint32

Summary AgentTraceSummaryOptional

Summary totals and trends for the requested date range.

ByModel []AgentTraceModelBreakdownOptional

Per-model breakdown of session stats.

LinesAdded stringOptional

Lines added by sessions using this model.

LinesRemoved stringOptional

Lines removed by sessions using this model.

Model SupportedModelOptional

The model these stats are for.

One of the following:

const SupportedModelUnspecified SupportedModel = "SUPPORTED_MODEL_UNSPECIFIED"

const SupportedModelSonnet3_5 SupportedModel = "SUPPORTED_MODEL_SONNET_3_5"

const SupportedModelSonnet3_7 SupportedModel = "SUPPORTED_MODEL_SONNET_3_7"

const SupportedModelSonnet3_7Extended SupportedModel = "SUPPORTED_MODEL_SONNET_3_7_EXTENDED"

const SupportedModelSonnet4 SupportedModel = "SUPPORTED_MODEL_SONNET_4"

const SupportedModelSonnet4Extended SupportedModel = "SUPPORTED_MODEL_SONNET_4_EXTENDED"

const SupportedModelSonnet4_5 SupportedModel = "SUPPORTED_MODEL_SONNET_4_5"

const SupportedModelSonnet4_5Extended SupportedModel = "SUPPORTED_MODEL_SONNET_4_5_EXTENDED"

const SupportedModelSonnet4_6 SupportedModel = "SUPPORTED_MODEL_SONNET_4_6"

const SupportedModelSonnet4_6Extended SupportedModel = "SUPPORTED_MODEL_SONNET_4_6_EXTENDED"

const SupportedModelSonnet5 SupportedModel = "SUPPORTED_MODEL_SONNET_5"

const SupportedModelOpus4 SupportedModel = "SUPPORTED_MODEL_OPUS_4"

const SupportedModelOpus4Extended SupportedModel = "SUPPORTED_MODEL_OPUS_4_EXTENDED"

const SupportedModelOpus4_5 SupportedModel = "SUPPORTED_MODEL_OPUS_4_5"

const SupportedModelOpus4_5Extended SupportedModel = "SUPPORTED_MODEL_OPUS_4_5_EXTENDED"

const SupportedModelOpus4_6 SupportedModel = "SUPPORTED_MODEL_OPUS_4_6"

const SupportedModelOpus4_6Extended SupportedModel = "SUPPORTED_MODEL_OPUS_4_6_EXTENDED"

const SupportedModelOpus4_7 SupportedModel = "SUPPORTED_MODEL_OPUS_4_7"

const SupportedModelOpus4_8 SupportedModel = "SUPPORTED_MODEL_OPUS_4_8"

const SupportedModelHaiku4_5 SupportedModel = "SUPPORTED_MODEL_HAIKU_4_5"

const SupportedModelOpenAI4O SupportedModel = "SUPPORTED_MODEL_OPENAI_4O"

const SupportedModelOpenAI4OMini SupportedModel = "SUPPORTED_MODEL_OPENAI_4O_MINI"

const SupportedModelOpenAIO1 SupportedModel = "SUPPORTED_MODEL_OPENAI_O1"

const SupportedModelOpenAIO1Mini SupportedModel = "SUPPORTED_MODEL_OPENAI_O1_MINI"

const SupportedModelOpenAIAuto SupportedModel = "SUPPORTED_MODEL_OPENAI_AUTO"

Sessions stringOptional

Number of sessions that used this model.

TotalLinesAdded stringOptional

Total lines added across all sessions.

TotalLinesAddedTrend float64Optional

Fractional change in total_lines_added compared to the previous period.

formatdouble

TotalLinesRemoved stringOptional

Total lines removed across all sessions.

TotalLinesRemovedTrend float64Optional

Fractional change in total_lines_removed compared to the previous period.

formatdouble

TotalSessions stringOptional

Total number of agent trace sessions in the date range.

TotalSessionsTrend float64Optional

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

Go

HTTP

TypeScript

Python

Go

package main

import (
  "context"
  "fmt"
  "time"

  "github.com/gitpod-io/gitpod-sdk-go"
  "github.com/gitpod-io/gitpod-sdk-go/option"
  "github.com/gitpod-io/gitpod-sdk-go/shared"
)

func main() {
  client := gitpod.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  response, err := client.Usage.GetAgentTraceSummary(context.TODO(), gitpod.UsageGetAgentTraceSummaryParams{
    DateRange: gitpod.F(shared.DateRangeParam{
      EndTime: gitpod.F(time.Now()),
      StartTime: gitpod.F(time.Now()),
    }),
    ProjectID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Sparkline)
}

200 example

{
  "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

200 example

{
  "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
  }
}