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"
{
"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"
}
API
List check-run agent billing summaries
Credit usage grouped by repository and check-run agent for a time interval.
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"
{
"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"
}
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.
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
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.
404.
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.string
required
Bearer <key>. See Authentication.Path parameters
string
required
GITHUB_ORGANIZATION or GITHUB_USER.string
required
Numeric GitHub ID of the organization or user, as a string. Must match the key’s workspace.
Query parameters
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.string
required
Exclusive upper bound (RFC 3339). Must follow
startTime by at most 366 elapsed 24-hour days. There are no implicit date defaults.integer
default:"50"
Maximum groups per page, 1 to 200. Explicit
0 is invalid. May change between pages.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
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.
Show properties
Show properties
string
Recorded repository ID, omitted when attribution is unavailable. Historical IDs need not resolve in the current repository catalog.
string
Recorded check-run agent name, not a distinct agent resource identifier.
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.
string
Total credits for the group, with three fractional digits (0.001 credit precision).
string
Minimum credits for one recorded usage event, with three fractional digits.
string
Maximum credits for one recorded usage event, with three fractional digits.
object
object
Nominal cost converted independently from
minimumCredits. Contains amount (decimal USD string, two fractional digits) and currency (USD).object
Nominal cost converted independently from
maximumCredits. Contains amount (decimal USD string, two fractional digits) and currency (USD).string
Latest recorded usage timestamp (RFC 3339), omitted when unavailable.
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.
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.string
Response time (RFC 3339), not a freshness watermark or snapshot identifier.
Errors
Missing or invalid dates, invalid page sizes and unusable tokens return400. Invalid date ordering and a span over 366 days have distinct error messages. Unavailable billing reads return 503. See shared authorization errors and limits.
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"
{
"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"
}