> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Insights API

<Note>Available on the Enterprise plan. [Contact sales](https://ona.com/contact/sales) to learn more.</Note>

The Insights API exposes the data behind the [Insights dashboard](/ona/organizations/insights): adoption and usage, AI co-authored commits, agent sessions, and PR speed. Use it to feed BI tools, build internal reports, or track AI adoption across teams.

For metric definitions and how to enable insights for projects, see [Insights](/ona/organizations/insights). Velocity and AI adoption endpoints return data only for projects with insights enabled.

## Authentication

All endpoints accept a Bearer token: a [personal access token](/ona/integrations/personal-access-token) (acts as you) or a [service account token](/ona/organizations/service-accounts) (owned by the organization, recommended for ongoing automation).

```bash theme={null}
export GITPOD_API_KEY="your-token"
```

## Request format

Every endpoint is a POST with a JSON body:

```text theme={null}
POST https://app.gitpod.io/api/gitpod.v1.UsageService/<Method>
```

| Parameter    | Required         | Description                                                                                         |
| ------------ | ---------------- | --------------------------------------------------------------------------------------------------- |
| `dateRange`  | Yes              | `startTime` and `endTime` as RFC-3339 timestamps. Maximum range is one year.                        |
| `projectId`  | No               | Scope results to a single project. Requires read access to that project.                            |
| `userId`     | No               | Scope results to a single user. Mutually exclusive with `teamId`.                                   |
| `teamId`     | No               | Scope results to members of a [team](/ona/organizations/teams). Mutually exclusive with `userId`.   |
| `resolution` | Time series only | Bucket size: `RESOLUTION_HOURLY`, `RESOLUTION_DAILY`, `RESOLUTION_WEEKLY`, or `RESOLUTION_MONTHLY`. |

Responses follow two conventions:

* All `*Trend` fields are the fractional change against the previous period of equal length, computed as `(current - previous) / previous`. For example, `0.25` means up 25% and `-0.1` means down 10%.
* 64-bit integer fields (counts, line totals) are returned as JSON strings, per protobuf JSON encoding. Parse them as integers.

## Adoption and usage summary

Returns active users, power users, environment sessions, and average environment runtime per user, each with a trend, plus a sparkline.

**Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.UsageService/GetAdoptionUsageSummary`

**Request:**

```bash theme={null}
curl https://app.gitpod.io/api/gitpod.v1.UsageService/GetAdoptionUsageSummary \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{"dateRange": {"startTime": "2026-06-09T00:00:00Z", "endTime": "2026-07-09T00:00:00Z"}}'
```

**Response:**

```json theme={null}
{
  "envRuntimePerUserSeconds": 431970.5,
  "envRuntimePerUserTrend": 0.12,
  "activeUsersCount": "48",
  "activeUsersTrend": 0.06,
  "powerUsersCount": "21",
  "powerUsersTrend": 0.1,
  "powerUsersThresholdSeconds": "308571",
  "sessionsCount": "12480",
  "sessionsTrend": -0.04,
  "sparkline": [
    { "time": "2026-06-09T00:00:00Z", "value": 44 },
    { "time": "2026-06-12T00:00:00Z", "value": 47 },
    { "time": "2026-06-15T00:00:00Z", "value": 51 }
  ]
}
```

## AI co-authored commits summary

Returns commit totals, line changes, and distinct authors, broken down per AI tool. Attribution uses `Co-authored-by` git trailers; see [AI Adoption](/ona/organizations/insights#ai-adoption) for the detection rules.

**Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.UsageService/GetCoAuthorSummary`

**Request:**

```bash theme={null}
curl https://app.gitpod.io/api/gitpod.v1.UsageService/GetCoAuthorSummary \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{"dateRange": {"startTime": "2026-06-09T00:00:00Z", "endTime": "2026-07-09T00:00:00Z"}}'
```

**Response:**

```json theme={null}
{
  "summary": {
    "totalCommits": "412",
    "totalLinesAdded": "30480",
    "totalLinesRemoved": "9860",
    "distinctAuthors": "24",
    "byTool": [
      { "tool": "CO_AUTHOR_TOOL_NO_COAUTHOR", "commits": "118", "linesAdded": "4120", "linesRemoved": "1240", "distinctAuthors": "18" },
      { "tool": "CO_AUTHOR_TOOL_ONA", "commits": "232", "linesAdded": "21260", "linesRemoved": "7140", "distinctAuthors": "16" },
      { "tool": "CO_AUTHOR_TOOL_CLAUDE", "commits": "62", "linesAdded": "5100", "linesRemoved": "1480", "distinctAuthors": "9" }
    ],
    "totalCommitsTrend": 0.18,
    "totalLinesAddedTrend": 0.22,
    "totalLinesRemovedTrend": 0.09,
    "distinctAuthorsTrend": 0.04
  },
  "sparkline": [
    { "time": "2026-06-09T00:00:00Z", "value": 96 },
    { "time": "2026-06-16T00:00:00Z", "value": 104 }
  ]
}
```

`tool` is one of `CO_AUTHOR_TOOL_NO_COAUTHOR`, `CO_AUTHOR_TOOL_HUMAN_COAUTHOR`, `CO_AUTHOR_TOOL_ONA`, `CO_AUTHOR_TOOL_GITHUB_COPILOT`, `CO_AUTHOR_TOOL_CURSOR`, `CO_AUTHOR_TOOL_CLAUDE`, `CO_AUTHOR_TOOL_CODEX`, or `CO_AUTHOR_TOOL_OTHER`.

## AI co-authored commits time series

Returns the same contribution stats bucketed over time, including the AI-assisted share of lines added per bucket.

**Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.UsageService/GetCoAuthorTimeSeries`

**Request:**

```bash theme={null}
curl https://app.gitpod.io/api/gitpod.v1.UsageService/GetCoAuthorTimeSeries \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{
       "dateRange": {"startTime": "2026-06-09T00:00:00Z", "endTime": "2026-07-09T00:00:00Z"},
       "resolution": "RESOLUTION_WEEKLY"
     }'
```

**Response:**

```json theme={null}
{
  "timeSeries": [
    {
      "startTime": "2026-06-08T00:00:00Z",
      "byTool": [
        { "tool": "CO_AUTHOR_TOOL_NO_COAUTHOR", "commits": "31", "linesAdded": "1080", "linesRemoved": "320", "distinctAuthors": "12" },
        { "tool": "CO_AUTHOR_TOOL_ONA", "commits": "58", "linesAdded": "5410", "linesRemoved": "1830", "distinctAuthors": "14" }
      ],
      "totalLinesAdded": "6490",
      "totalLinesRemoved": "2150",
      "aiRatio": 0.83,
      "totalCommits": "89",
      "distinctAuthors": "16"
    },
    {
      "startTime": "2026-06-15T00:00:00Z",
      "byTool": [
        { "tool": "CO_AUTHOR_TOOL_ONA", "commits": "64", "linesAdded": "6220", "linesRemoved": "2040", "distinctAuthors": "15" }
      ],
      "totalLinesAdded": "6220",
      "totalLinesRemoved": "2040",
      "aiRatio": 1,
      "totalCommits": "64",
      "distinctAuthors": "15"
    }
  ]
}
```

## Agent sessions summary

Returns agent session counts and line changes, with a per-model breakdown.

**Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.UsageService/GetAgentTraceSummary`

**Request:**

```bash theme={null}
curl https://app.gitpod.io/api/gitpod.v1.UsageService/GetAgentTraceSummary \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{"dateRange": {"startTime": "2026-06-09T00:00:00Z", "endTime": "2026-07-09T00:00:00Z"}}'
```

**Response:**

```json theme={null}
{
  "summary": {
    "totalSessions": "1240",
    "totalLinesAdded": "382400",
    "totalLinesRemoved": "76110",
    "byModel": [
      { "model": "SUPPORTED_MODEL_OPUS_4_8", "sessions": "820", "linesAdded": "268900", "linesRemoved": "51200" },
      { "model": "SUPPORTED_MODEL_SONNET_5", "sessions": "420", "linesAdded": "113500", "linesRemoved": "24910" }
    ],
    "totalSessionsTrend": 0.31,
    "totalLinesAddedTrend": 0.27,
    "totalLinesRemovedTrend": 0.19
  },
  "sparkline": [
    { "time": "2026-06-09T00:00:00Z", "value": 274 },
    { "time": "2026-06-16T00:00:00Z", "value": 301 }
  ]
}
```

## Agent sessions time series

Returns agent sessions and line changes bucketed over time.

**Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.UsageService/GetAgentTraceTimeSeries`

**Request:**

```bash theme={null}
curl https://app.gitpod.io/api/gitpod.v1.UsageService/GetAgentTraceTimeSeries \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{
       "dateRange": {"startTime": "2026-06-09T00:00:00Z", "endTime": "2026-07-09T00:00:00Z"},
       "resolution": "RESOLUTION_WEEKLY"
     }'
```

**Response:**

```json theme={null}
{
  "timeSeries": [
    {
      "startTime": "2026-06-08T00:00:00Z",
      "totalSessions": "274",
      "totalLinesAdded": "84300",
      "totalLinesRemoved": "16750",
      "byModel": [
        { "model": "SUPPORTED_MODEL_OPUS_4_8", "sessions": "181", "linesAdded": "59400", "linesRemoved": "11300" },
        { "model": "SUPPORTED_MODEL_SONNET_5", "sessions": "93", "linesAdded": "24900", "linesRemoved": "5450" }
      ]
    }
  ]
}
```

## PR speed summary

Returns median lead time (first commit to merge), PRs merged, median time to first approval, and deployment frequency (PRs merged to the project's configured branch, per week).

**Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.UsageService/GetPrSummary`

**Request:**

```bash theme={null}
curl https://app.gitpod.io/api/gitpod.v1.UsageService/GetPrSummary \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{"dateRange": {"startTime": "2026-06-09T00:00:00Z", "endTime": "2026-07-09T00:00:00Z"}}'
```

**Response:**

```json theme={null}
{
  "summary": {
    "leadTimeSeconds": 8131.5,
    "leadTimeTrend": -0.14,
    "prsMergedCount": "648",
    "prsMergedTrend": 0.08,
    "timeToFirstApprovalSeconds": 821,
    "timeToFirstApprovalTrend": -0.05,
    "deploymentFrequency": 149.3,
    "deploymentFrequencyTrend": 0.11
  },
  "sparkline": [
    { "time": "2026-06-09T00:00:00Z", "value": 148 },
    { "time": "2026-06-16T00:00:00Z", "value": 162 }
  ]
}
```

`timeToFirstApprovalSeconds` is zero when no PRs in the range had approvals. For lead time and time to first approval, a negative trend means faster shipping.

## PR speed time series

Returns the same PR metrics bucketed over time.

**Endpoint:** `POST https://app.gitpod.io/api/gitpod.v1.UsageService/GetPrTimeSeries`

**Request:**

```bash theme={null}
curl https://app.gitpod.io/api/gitpod.v1.UsageService/GetPrTimeSeries \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{
       "dateRange": {"startTime": "2026-06-09T00:00:00Z", "endTime": "2026-07-09T00:00:00Z"},
       "resolution": "RESOLUTION_WEEKLY"
     }'
```

**Response:**

```json theme={null}
{
  "timeSeries": [
    {
      "startTime": "2026-06-09T00:00:00Z",
      "leadTimeSeconds": 6428,
      "prsMergedCount": "320",
      "timeToFirstApprovalSeconds": 958,
      "deploys": "313"
    },
    {
      "startTime": "2026-06-16T00:00:00Z",
      "leadTimeSeconds": 10894,
      "prsMergedCount": "147",
      "timeToFirstApprovalSeconds": 803,
      "deploys": "146"
    }
  ]
}
```

## Combining filters

Scope any endpoint with the shared parameters. For example, a single team's weekly co-author trend:

```bash theme={null}
curl https://app.gitpod.io/api/gitpod.v1.UsageService/GetCoAuthorTimeSeries \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{
       "dateRange": {"startTime": "2026-06-09T00:00:00Z", "endTime": "2026-07-09T00:00:00Z"},
       "teamId": "<team-id>",
       "resolution": "RESOLUTION_WEEKLY"
     }'
```