---
updatedAt: 2026-07-27T21:05:06.000Z
agentTools:
  projectIndex: https://devx.pax8.com/llms.txt
---

# Get All Usage Lines

A `subscriptionId` OR an `externalSubscriptionId` is required.

There are two ways to retrieve usage lines:

- **With `summaryKey`** — returns all usage lines for that summary
  key, without pagination.
- **Without `summaryKey`** — returns paginated results of all usage
  lines for the subscription. Use the `page` and `size` parameters
  to control pagination.


# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Vendor Usage Endpoints",
    "description": "Vendor Usage Endpoints",
    "version": "v0"
  },
  "servers": [
    {
      "url": "https://api.pax8.com/v2/usage",
      "description": "Pax8 API"
    }
  ],
  "security": [
    {
      "OAuth2": []
    }
  ],
  "paths": {
    "/lines": {
      "get": {
        "tags": [
          "Usage Lines"
        ],
        "summary": "Get All Usage Lines",
        "description": "A `subscriptionId` OR an `externalSubscriptionId` is required.\n\nThere are two ways to retrieve usage lines:\n\n- **With `summaryKey`** — returns all usage lines for that summary\n  key, without pagination.\n- **Without `summaryKey`** — returns paginated results of all usage\n  lines for the subscription. Use the `page` and `size` parameters\n  to control pagination.\n",
        "operationId": "getUsageLines",
        "parameters": [
          {
            "name": "subscriptionId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "externalSubscriptionId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "billingPeriod",
            "in": "query",
            "description": "Billing period with format yyyy-MM",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "summaryKey",
            "in": "query",
            "description": "Optional. Filter by specific summary key. When provided the response isn't paginated.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "isSimulation",
            "in": "query",
            "description": "When set to true, returns simulated usage lines instead of production usage lines",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number (0-based). Only used when summaryKey is not provided.",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 0
            }
          },
          {
            "name": "size",
            "in": "query",
            "description": "Page size (max 100). Only used when summaryKey is not provided.",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/PageDTOUsageLine"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UsageLine": {
        "required": [
          "productId",
          "quantity",
          "summaryDisplayName",
          "summaryKey",
          "unitOfMeasurement"
        ],
        "type": "object",
        "properties": {
          "summaryKey": {
            "maxLength": 255,
            "type": "string"
          },
          "summaryDisplayName": {
            "maxLength": 255,
            "type": "string"
          },
          "quantity": {
            "minimum": 0,
            "type": "number"
          },
          "productId": {
            "type": "string",
            "format": "uuid"
          },
          "unitOfMeasurement": {
            "type": "string"
          }
        }
      },
      "PageDTOUsageLine": {
        "required": [
          "content",
          "page"
        ],
        "type": "object",
        "properties": {
          "content": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UsageLine"
            }
          },
          "page": {
            "$ref": "#/components/schemas/PageInfo"
          }
        }
      },
      "PageInfo": {
        "required": [
          "number",
          "size",
          "totalElements",
          "totalPages"
        ],
        "type": "object",
        "properties": {
          "size": {
            "type": "integer",
            "format": "int32"
          },
          "totalElements": {
            "type": "integer",
            "format": "int64"
          },
          "totalPages": {
            "type": "integer",
            "format": "int32"
          },
          "number": {
            "type": "integer",
            "format": "int32"
          }
        }
      }
    },
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "description": "Requires 'audience' parameter in token request: `api://usage`.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.pax8.com/v1/token",
            "scopes": {
              "read:usageLine": "Grants read access for usage",
              "write:usageLine": "Grants write access for usage"
            }
          }
        }
      }
    }
  }
}
```