Usage API

List usage records

GET /api/v1/usage

const { data: records } = await puchify.usage.list({
  from: "2026-05-01T00:00:00Z",
  to: "2026-05-31T23:59:59Z",
})

records = puchify.usage.list(
  from="2026-05-01T00:00:00Z",
  to="2026-05-31T23:59:59Z",
)

records, err := client.Usage.List(ctx, &puchify.UsageListParams{
  From: puchify.String("2026-05-01T00:00:00Z"),
  To:   puchify.String("2026-05-31T23:59:59Z"),
})

puchify usage list --from 2026-05-01T00:00:00Z --to 2026-05-31T23:59:59Z

curl "https://api.puchify.com/api/v1/usage?from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z" \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Query parameters:

Parameter	Type	Description
`resource_id`	string	Filter by resource ID
`resource_kind`	string	Filter by resource kind
`from`	string	Start period (ISO 8601)
`to`	string	End period (ISO 8601)
`cursor`	string	Pagination cursor
`limit`	integer (1-100)	Results per page (default 50)
`order`	`asc` \| `desc`	Sort direction (default: `desc`)

Get usage summary

GET /api/v1/usage/summary

const { data: summary } = await puchify.usage.getSummary()

summary = puchify.usage.get_summary()

summary, err := client.Usage.GetSummary(ctx)

puchify usage summary

curl https://api.puchify.com/api/v1/usage/summary \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Returns aggregated totals for the current billing period.

Get invoice list

GET /api/v1/usage/invoices

const { data: invoices } = await puchify.usage.listInvoices()

invoices = puchify.usage.list_invoices()

invoices, err := client.Usage.ListInvoices(ctx)

puchify usage invoices

curl https://api.puchify.com/api/v1/usage/invoices \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Query parameters:

Parameter	Type	Description
`status`	`open` \| `paid` \| `overdue` \| `void`	Filter by invoice status
`cursor`	string	Pagination cursor
`limit`	integer (1-100)	Results per page (default 50)

Response shape

{
  "data": {
    "usage_records": [
      {
        "id": "ur_001",
        "resource_id": "svr_abc123",
        "resource_kind": "server",
        "resource_name": "web-01",
        "category": "compute",
        "plan": "shared-2",
        "quantity": 720.0,
        "unit": "hours",
        "rate": 0.014,
        "cost": 10.08,
        "period_start": "2026-05-01T00:00:00Z",
        "period_end": "2026-05-31T23:59:59Z"
      }
    ],
    "summary": {
      "period_start": "2026-05-01T00:00:00Z",
      "period_end": "2026-05-31T23:59:59Z",
      "total_cost": 142.50,
      "currency": "USD",
      "by_category": {
        "compute": 85.20,
        "storage": 32.30,
        "network": 25.00
      }
    },
    "invoices": [
      {
        "id": "inv_001",
        "status": "paid",
        "total": 142.50,
        "currency": "USD",
        "issued_at": "2026-06-01T00:00:00Z",
        "paid_at": "2026-06-01T03:00:00Z",
        "pdf_url": "https://billing.puchify.com/invoices/inv_001.pdf"
      }
    ]
  },
  "meta": {
    "persistence": "synced"
  }
}

Error codes

Code	Description
`422`	Invalid date range or pagination parameters

Usage API

List usage records

Get usage summary

Get invoice list

Response shape

Error codes

On this page