API Reference

Usage

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

GetAgentTraceTimeSeries

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"

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.

resolution: optional Resolution

Time resolution for the series data.

One of the following:

"RESOLUTION_UNSPECIFIED"

"RESOLUTION_HOURLY"

"RESOLUTION_DAILY"

"RESOLUTION_WEEKLY"

"RESOLUTION_MONTHLY"

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

timeSeries: optional array of AgentTraceTimeBucket { byModel, startTime, totalLinesAdded, 2 more }

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

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

Per-model breakdown for this bucket.

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.

startTime: optional string

Start of this time bucket.

formatdate-time

totalLinesAdded: optional string

Total lines added in this bucket.

totalLinesRemoved: optional string

Total lines removed in this bucket.

totalSessions: optional string

Number of agent trace sessions in this bucket.

GetAgentTraceTimeSeries

HTTP

HTTP

TypeScript

Python

Go

curl https://app.gitpod.io/api/gitpod.v1.UsageService/GetAgentTraceTimeSeries \
    -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"
          }
        }'

200 example

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

200 example

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