## 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

```yaml
dateRange:
  startTime: "2024-01-01T00:00:00Z"
  endTime: "2024-02-01T00:00:00Z"
projectId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

### Parameters

- `body UsageGetAgentTraceSummaryParams`

  - `DateRange param.Field[DateRange]`

    Date range to query within.

  - `ProjectID param.Field[string]`

    Optional project ID to scope results.

  - `TeamID param.Field[string]`

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

  - `UserID param.Field[string]`

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

### Returns

- `type UsageGetAgentTraceSummaryResponse struct{…}`

  - `Sparkline []TimeSeriesPoint`

    Sparkline data for card rendering.

    - `Time Time`

      Timestamp for this data point.

    - `Value int64`

      The numerical value for this data point.

  - `Summary AgentTraceSummary`

    Summary totals and trends for the requested date range.

    - `ByModel []AgentTraceModelBreakdown`

      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.

        - `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 string`

        Number of sessions that used this model.

    - `TotalLinesAdded string`

      Total lines added across all sessions.

    - `TotalLinesAddedTrend float64`

      Fractional change in total_lines_added compared to the previous period.

    - `TotalLinesRemoved string`

      Total lines removed across all sessions.

    - `TotalLinesRemovedTrend float64`

      Fractional change in total_lines_removed compared to the previous period.

    - `TotalSessions string`

      Total number of agent trace sessions in the date range.

    - `TotalSessionsTrend float64`

      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

```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)
}
```

#### 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
  }
}
```