---
title: "List merged Trails with their agent usage metrics, newest merge first"
method: GET
path: "/api/v1/insights/{forge}/{project}/trail-metrics"
tags: ["Insights"]
---

# List merged Trails with their agent usage metrics, newest merge first

`GET /api/v1/insights/{forge}/{project}/trail-metrics`

## Request

- Base URL: `https://entire.io` (the document declares no server; this is the origin it was published from)
- URL: `https://entire.io/api/v1/insights/{forge}/{project}/trail-metrics`
- Auth: none declared

## Path parameters

- `forge` 'gh' | 'et', required
- `project` string, required

## Query parameters

- `repo_id` string, required
- `since` string, date-time
- `until` string, date-time
- `per_page` integer
- `batch_pages` integer
- `cursor` string
- `has_agent_data` boolean

## Response `200`

A page of merged Trails with usage metrics

- object
  - `trail_metrics` object[], required
    - `repo_id` string, required: The repository's public repo_<group> id.
    - `number` integer, required
    - `merged_at` string, date-time, required
    - `sessions` integer, required
    - `size` object
      - `additions` integer, required
      - `deletions` integer, required
      - `files_changed` integer, required
      - `truncated` boolean, required
      - `bucket` 'S' | 'M' | 'L' | 'XL', required
    - `models` object[], required
      - `agent` string, required
      - `model` string, required
      - `calls` integer, required
      - `tokens` object, required
        - `fresh_input` integer, required
        - `cache_read` integer, required
        - `cache_write_5m` integer, required
        - `cache_write_1h` integer, required
        - `output` integer, required
    - `phases` object[]
      - `phase` string, required
      - `tokens` object, required
        - `fresh_input` integer, required
        - `cache_read` integer, required
        - `cache_write_5m` integer, required
        - `cache_write_1h` integer, required
        - `output` integer, required
    - `review` object: Review tokens over every hosted review run. Absent until the Trail's review spend is recorded; a recorded Trail with no review runs has tokens 0.
      - `tokens` integer, required
  - `next_cursor` string

## Other responses

- `400`: Invalid request or cursor
- `401`: Not authenticated
- `403`: Feature disabled, or the upstream's problem+json for a caller without access to the project
- `404`: Project not found, or the upstream plugin-not-installed problem+json (https://entire.io/errors/insights/plugin-not-installed)
- `422`: Invalid project name
- `500`: Insights service error (upstream problem+json passed through)
- `502`: Insights service unavailable
- `503`: Insights service unavailable (upstream problem+json passed through)

## Changes

- **2026-11-02** `d09ae166aae2`: 1 warning
  - changed the pattern of the `query` request parameter `repo_id` from `^(?:repo_)?[0-7][0-9A-HJKMNP-TV-Z]{25}$` to `^repo_[0-7][0-9A-HJKMNP-TV-Z]{25}$`
- **2026-10-30** `4b5f58b32a6b`: 1 warning, 1 info
  - removed the optional property `trail_metrics/items/runners` from the response with the `200` status
  - added the optional property `trail_metrics/items/review` to the response with the `200` status
- **2026-10-29** `ad35574a59f1`: 1 warning
  - changed the pattern of the `query` request parameter `repo_id` from `^[0-7][0-9A-HJKMNP-TV-Z]{25}$` to `^(?:repo_)?[0-7][0-9A-HJKMNP-TV-Z]{25}$`
- **2026-10-21** `6e2b6804e0a1`: 2 info
  - added the new optional `query` request parameter `has_agent_data`
  - added the optional property `trail_metrics/items/runners` to the response with the `200` status
- **2026-10-20** `7f46eb602a2e`: 1 info
  - added the new optional `query` request parameter `batch_pages`

[Operation history](https://skmtc.dev/entire/apis/entire-api/changes/api/v1/insights/:forge/:project/trail-metrics/get.md)

---

[API](https://skmtc.dev/entire/apis/entire-api.md) - [All operations](https://skmtc.dev/entire/apis/entire-api/llms.txt) - [OpenAPI document](https://skmtc.dev/entire/apis/entire-api/revisions/a24dfcc828d7?raw)