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

# List check-run agent billing summaries

> Credit usage grouped by repository and check-run agent for a time interval.

Returns complete credit-usage aggregates per repository and recorded check-run agent name over a required interval. Each group's totals are calculated before pagination. For individual usage records, see [List agent credit usage](https://docs.macroscope.com/api-reference/endpoint/list-agent-credit-usage.md).

Visibility is workspace-wide, including historical usage from excluded or deleted repositories and usage without repository attribution. Repository restrictions do not filter these totals or grant access to repository content. An interval with no matching usage returns an empty collection, not `404`.

> [!NOTE]
>
> Credit quantities are exact decimal strings with three fractional digits. Costs are provisional nominal USD at the current customer credit rate, not billed or invoiced amounts, and can include unmetered activity. They do not reconcile to an invoice.

## Authorization

Requires workspace Read. API keys can read only their bound workspace and do not inherit their creator's Admin permissions.

**Authorization** `string` *required*

`Bearer <key>`. See [Authentication](https://docs.macroscope.com/api#authentication).

## Path parameters

**workspaceType** `string` *required*

`GITHUB_ORGANIZATION` or `GITHUB_USER`.

**workspaceId** `string` *required*

Numeric GitHub ID of the organization or user, as a string. Must match the key's workspace.

## Query parameters

**startTime** `string` *required*

Inclusive lower bound of `[startTime, endTime)` (RFC 3339). Boundaries are UTC instants at microsecond precision, independent of workspace timezone; finer fractional digits are discarded when selecting usage.

**endTime** `string` *required*

Exclusive upper bound (RFC 3339). Must follow `startTime` by at most 366 elapsed 24-hour days. There are no implicit date defaults.

**pageSize** `integer` (default: 50)

Maximum groups per page, 1 to 200. Explicit `0` is invalid. May change between pages.

**pageToken** `string`

Opaque `nextPageToken` from the preceding page, bound to workspace, operation and dates. Repeat the original dates. Valid for at most 24 hours, subject to earlier invalidation. Invalid, altered, expired or mismatched tokens return `400` without identifying the failed token check; restart without a token.

## Response

**summaries** `object[]`

Complete repository/agent groups sorted by repository ID ascending (missing ID first), then agent name ascending, using case-sensitive UTF-8 byte ordering. Omitted when no groups match; treat absence as an empty list.

**properties**

**repositoryId** `string`

Recorded repository ID, omitted when attribution is unavailable. Historical IDs need not resolve in the current repository catalog.

**checkRunName** `string`

Recorded check-run agent name, not a distinct agent resource identifier.

**runCount** `string`

Number of recorded custom-review usage events with this nonempty name, including zero-credit events. An int64 decimal string, not a count of distinct executions.

**totalCredits** `string`

Total credits for the group, with three fractional digits (0.001 credit precision).

**minimumCredits** `string`

Minimum credits for one recorded usage event, with three fractional digits.

**maximumCredits** `string`

Maximum credits for one recorded usage event, with three fractional digits.

**totalNominalCost** `object`

Nominal cost converted independently from `totalCredits` at the current rate.

**properties**

**amount** `string`

Decimal amount in USD, rounded to two fractional digits.

**currency** `string`

`USD`.

**minimumNominalCost** `object`

Nominal cost converted independently from `minimumCredits`. Contains `amount` (decimal USD string, two fractional digits) and `currency` (`USD`).

**maximumNominalCost** `object`

Nominal cost converted independently from `maximumCredits`. Contains `amount` (decimal USD string, two fractional digits) and `currency` (`USD`).

**lastRunTime** `string`

Latest recorded usage timestamp (RFC 3339), omitted when unavailable.

**latestPullRequestNumber** `string`

PR number of that latest usage event, as an int64 decimal string. Omitted if that event has no PR context; not the latest nonempty PR from earlier events.

**nextPageToken** `string`

Pass as `pageToken` with the same dates to continue. Omitted when no further groups remain in this read. Follow any returned token even on a short or empty page.

**readTime** `string`

Response time (RFC 3339), not a freshness watermark or snapshot identifier.

Costs round to the nearest cent, with ties away from zero. Each total, minimum and maximum is converted from its corresponding credit quantity, not summed from rounded event dollars. Summing group costs can differ from converting their combined credits. Use credit quantities for sub-cent analysis.

Pages are live reads. Amounts, counts and latest usage can change between pages without moving an existing group across page boundaries. New groups before the continuation position can be missed; new groups after it can appear, and deleted groups disappear. Following all tokens does not provide a snapshot-consistent export; restart for a fresh listing.

## Errors

Missing or invalid dates, invalid page sizes and unusable tokens return `400`. Invalid date ordering and a span over 366 days have distinct error messages. Unavailable billing reads return `503`. See [shared authorization errors and limits](https://docs.macroscope.com/api#errors).

```bash cURL theme={null}
curl "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/checkRunAgentSummaries?startTime=2026-09-01T00%3A00%3A00Z&endTime=2026-10-01T00%3A00%3A00Z&pageSize=50" \
  -H "Authorization: Bearer $MACROSCOPE_API_KEY"
```

```json 200 theme={null}
{
  "summaries": [
    {
      "repositoryId": "repo_abc123",
      "checkRunName": "Security review",
      "runCount": "2",
      "totalCredits": "3.000",
      "minimumCredits": "1.000",
      "maximumCredits": "2.000",
      "totalNominalCost": { "amount": "0.03", "currency": "USD" },
      "minimumNominalCost": { "amount": "0.01", "currency": "USD" },
      "maximumNominalCost": { "amount": "0.02", "currency": "USD" },
      "lastRunTime": "2026-09-30T12:00:00Z",
      "latestPullRequestNumber": "42"
    }
  ],
  "readTime": "2026-10-01T09:00:00Z"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.