> ## 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 billing meter summaries

> Per-meter usage quantities and provisional priced amounts for a time interval.

Returns one row per meter with the complete usage total for the requested interval, sorted by `meterCode`. Amounts cover the whole workspace and are provisional. Follow every page to list all meters.

For a daily series instead of one interval total per meter, use [daily billing usage](https://docs.macroscope.com/api-reference/endpoint/list-daily-billing-usage.md). Daily usage keeps independent rate series separate, including multiple rates on one meter.

Requires workspace Read. API keys can read only their bound workspace. Excluded/deleted repositories and unattributed usage remain included. Totals can lag activity; complete here means the requested interval's total for each returned meter, not a guarantee of processing completeness or a final invoice.

Usage may be cached for up to one minute, and subscription and pricing information for up to five minutes. Even historical totals are provisional: they are not invoice amounts, balances, or net charges. Pages do not form a snapshot, and `readTime` is not a freshness guarantee.

## 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. Usage is bucketed by UTC day, with minute resolution at partial-day boundaries.

**endTime** `string` *required*

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

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

Rows 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

**meters** `object[]`

Meter totals on this page.

**properties**

**id** `string`

Opaque row identifier.

**meterCode** `string`

Opaque meter code.

**displayName** `string`

Meter display name.

**quantity** `string`

Decimal usage quantity in `unit`.

**unit** `string`

Unit of `quantity`. Byte meters priced per KB report KB (1000 bytes), rounded daily to two decimals.

**usageAmount** `Money`

Priced usage for the interval. Each UTC day is priced separately and rounded to cents.

**periodStart** `string`

Start of the summarized interval (RFC 3339).

**periodEnd** `string`

End of the summarized interval (RFC 3339).

**amountStatus** `string`

Always `BILLING_AMOUNT_STATUS_PROVISIONAL`. Totals can change and can lag recent activity.

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

An omitted Money object means no value, not zero.

**amount** `string`

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

**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/meterSummaries \
  -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/meterSummaries",
    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/meterSummaries?${params}`,
  { headers: { Authorization: `Bearer ${process.env.MACROSCOPE_API_KEY}` } }
);
console.log(await res.json());
```

```json 200 theme={null}
{
  "meters": [
    {
      "id": "meter_abc123",
      "meterCode": "meter_code_1",
      "displayName": "Example meter",
      "quantity": "2500.00",
      "unit": "KB",
      "usageAmount": {
        "amount": "125.00",
        "currency": "USD"
      },
      "periodStart": "2026-09-01T00:00:00Z",
      "periodEnd": "2026-10-01T00:00:00Z",
      "amountStatus": "BILLING_AMOUNT_STATUS_PROVISIONAL"
    }
  ],
  "nextPageToken": "token_def456",
  "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.