---
title: "Fetch usage summaries for a plan and customer"
method: GET
path: "/plans/{planId}/usage"
tags: ["plans"]
---

# Fetch usage summaries for a plan and customer

`GET /plans/{planId}/usage`

## Request

- Base URL: `https://api.agentpaid.io/api/v1`
- URL: `https://api.agentpaid.io/api/v1/plans/{planId}/usage`
- Auth: HTTP bearer

## Path parameters

- `planId` string, uuid, required

## Query parameters

- `externalId` string, required
- `limit` integer
- `offset` integer
- `startTime` string, date-time
- `endTime` string, date-time

## Response `200`

Success response

- UsageSummariesResponse: Response containing usage summaries and pagination metadata
  - `data` UsageSummary[], required
    - `id` string, uuid, required: The unique identifier of the usage summary
    - `eventName` string, required: The name of the event being tracked
    - `eventsQuantity` integer, required: The quantity of events in this usage period
    - `signalCount` integer: The number of signals that contributed to this usage period
    - `startDate` string, date-time, required: The start date of the usage period
    - `endDate` string, date-time, required: The end date of the usage period
    - `subtotal` integer, required: The rated amount in the smallest currency unit (e.g., cents). Fixed at the amount billing settled once the period is billed or skipped; an estimate at current prices while the period is still collecting.
    - `currency` string: The currency code of the subtotal
    - `status` 'collecting' | 'billed' | 'skipped': collecting while the period is open, then the billing verdict: billed onto an invoice line, or skipped with no charge.
    - `nextBillingDate` string, date-time, required: The next billing date for this usage
    - `customerId` string, uuid, required: The internal customer ID
    - `orderId` string, uuid, required: The order ID associated with this usage
    - `orderLineId` string, uuid, required: The order line ID associated with this usage
    - `orderLineAttributeId` string, uuid, required: The order line attribute ID associated with this usage
    - `invoiceId` string, uuid, nullable: The invoice ID if this usage has been invoiced
    - `invoiceLineId` string, uuid, nullable: The invoice line ID if this usage has been invoiced
    - `createdAt` string, date-time, required: When the usage summary was created
    - `updatedAt` string, date-time, required: When the usage summary was last updated
    - `order` UsageSummaryOrder: Associated order information
      - `id` string, uuid
      - `displayId` string, nullable
    - `orderLine` UsageSummaryOrderLine: Associated order line information
      - `id` string, uuid
      - `displayId` string, nullable
  - `pagination` UsagePaginationMeta, required: Pagination metadata for usage summaries
    - `limit` integer, required: The requested limit
    - `offset` integer, required: The requested offset
    - `total` integer, required: Total number of usage summaries available
    - `hasMore` boolean, required: Whether there are more results available

## Other responses

- `400`: Bad request - Invalid query parameters
- `403`: Forbidden - Invalid or missing API key
- `404`: Plan or customer not found

---

[API](https://skmtc.dev/paid/apis/paid-2.md) - [All operations](https://skmtc.dev/paid/apis/paid-2/llms.txt) - [OpenAPI document](https://skmtc.dev/paid/apis/paid-2/revisions/dbdf4a60ed27?raw)