> ## 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 agent credit usage

> Recorded agent credit usage with attribution and nominal cost, newest first.

Returns agent credit usage records for the requested interval, newest first. Records cover the whole workspace. Nominal costs are not invoice amounts; use List billing meter summaries for priced usage.

Requires workspace Read. API keys can read only their bound workspace. Excluded/deleted repositories and unattributed usage remain included. Unmetered records can also appear; do not sum these nominal costs to reproduce an invoice.

## Authorization

**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.

## Query parameters

**startTime** `string` *required*

Inclusive start of the interval (RFC 3339). The interval is half-open, `[startTime, endTime)`, and at most 366 days.

**endTime** `string` *required*

Exclusive end of the interval (RFC 3339). Must be after `startTime`.

**source** `string`

Filter to one source. Omit for all sources. One of `BILLING_USAGE_SOURCE_QUERY_AGENT`, `BILLING_USAGE_SOURCE_WEBHOOK`, `BILLING_USAGE_SOURCE_SCHEDULED_MACRO`, `BILLING_USAGE_SOURCE_MACRO`, `BILLING_USAGE_SOURCE_CLI_REVIEW`, `BILLING_USAGE_SOURCE_CHECK_RUN`, `BILLING_USAGE_SOURCE_PR_ASSISTANT`, `BILLING_USAGE_SOURCE_APPROVABILITY`, `BILLING_USAGE_SOURCE_GITHUB_ACTIONS`.

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

Records per page, 1 to 200.

**pageToken** `string`

`nextPageToken` from the previous response. Keep all other parameters unchanged except `pageSize`. Tokens expire after 24 hours; on a 400, restart without a token.

## Response

**usage** `object[]`

Usage records on this page. Attribution fields are omitted when unknown.

**properties**

**id** `string`

Opaque record identifier.

**createdAt** `string`

When the usage was recorded (RFC 3339).

**source** `string`

Activity that used the credits. A `BILLING_USAGE_SOURCE_` value; unrecognized sources return `BILLING_USAGE_SOURCE_UNKNOWN`.

**credits** `string`

Decimal credits used, to 1/1000 credit.

**nominalCost** `Money`

USD cost at the workspace's current credit rate, rounded to cents. Not the historical invoice price.

**repositoryId** `string`

Opaque ID of the attributed repository.

**pullRequestNumber** `string`

Attributed pull request number (int64 as string).

**githubUserId** `string`

Attributed GitHub user ID (int64 as string).

**checkName** `string`

Attributed check name.

**macroId** `string`

Attributed macro ID.

**detectionMode** `string`

Detection mode label, when applicable.

**nextPageToken** `string`

Token for the next page. Omitted on the last page.

**readTime** `string`

When the response was generated (RFC 3339). Not a data freshness timestamp.

### Money

Summing rounded `nominalCost` values can differ from the rounded total.

**amount** `string`

Decimal amount in major units, e.g. `"0.13"`.

**currency** `string`

ISO 4217 code, e.g. `"USD"`.

```bash cURL theme={null}
curl --get https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/agentCreditUsage \
  -H "Authorization: Bearer $MACROSCOPE_API_KEY" \
  --data-urlencode "startTime=2026-09-01T00:00:00Z" \
  --data-urlencode "endTime=2026-10-01T00:00:00Z" \
  --data-urlencode "pageSize=50"
```

```python Python theme={null}
import os, requests

r = requests.get(
    "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/agentCreditUsage",
    headers={"Authorization": f"Bearer {os.environ['MACROSCOPE_API_KEY']}"},
    params={
        "startTime": "2026-09-01T00:00:00Z",
        "endTime": "2026-10-01T00:00:00Z",
        "pageSize": 50,
    },
)
print(r.json())
```

```javascript JavaScript theme={null}
const params = new URLSearchParams({
  startTime: "2026-09-01T00:00:00Z",
  endTime: "2026-10-01T00:00:00Z",
  pageSize: "50",
});
const res = await fetch(
  `https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/agentCreditUsage?${params}`,
  { headers: { Authorization: `Bearer ${process.env.MACROSCOPE_API_KEY}` } }
);
console.log(await res.json());
```

```json 200 theme={null}
{
  "usage": [
    {
      "id": "usage_abc123",
      "createdAt": "2026-09-15T12:00:00Z",
      "source": "BILLING_USAGE_SOURCE_CHECK_RUN",
      "credits": "1.250",
      "nominalCost": {
        "amount": "0.13",
        "currency": "USD"
      },
      "repositoryId": "repo_abc123",
      "pullRequestNumber": "42",
      "checkName": "Example check"
    },
    {
      "id": "usage_def456",
      "createdAt": "2026-09-15T11:45:00Z",
      "source": "BILLING_USAGE_SOURCE_PR_ASSISTANT",
      "credits": "0.500",
      "nominalCost": {
        "amount": "0.05",
        "currency": "USD"
      },
      "repositoryId": "repo_abc123",
      "pullRequestNumber": "41"
    }
  ],
  "nextPageToken": "token_ghi789",
  "readTime": "2026-10-01T00:05:00Z"
}
```

```json 401 theme={null}
{ "code": 16, "message": "unauthenticated" }
```


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