GET /v1/organizations/:orgId/credits/events

A child organization's credit ledger - every charge, refund, grant, and parent→child allocation.

GET/v1/organizations/{orgId}/credits/events

Phase 1stable

Auth: Bearer
Scope: org:admin

To audit what a customer's wallet has done - what they spent, what you funded - read that child's credit ledger. You call this with your parent (org:admin) key. One row per wallet movement, same shape as your own GET /v1/credits/events, scoped to the child named in the path.

This is where parent→child funding shows up: every allocation lands here as an allocation event (positive on the child you funded), so the ledger reconciles the wallet you see in GET …/credits.

Results are keyset (cursor) paginated, newest first. Follow nextCursor until it returns null.

Query parameters

projectId
stringoptional
Filter to events attributed to one of the child's projects. Org-level events (grants, purchases, allocations) have a null projectId and are excluded when this filter is set.
eventType
stringoptional
Filter to one event type. See "Event types" below.
One of: usage, refund, grant, purchase, adjustment, allocation
since
string (ISO 8601 Z)optional
Only events `>= since`. UTC required (Z suffix; offset form like +00:00 is rejected).
until
string (ISO 8601 Z)optional
Only events `<= until`. UTC required (Z suffix).
cursor
stringoptional
Opaque cursor from the previous page.
limit
integeroptionaldefault: 25
Page size, 1-100.

Example

# Every allocation you've made into this child
curl "https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80/credits/events?eventType=allocation" \
  -H "Authorization: Bearer $LAYERS_PARENT_KEY"

200OK

{
  "items": [
    {
      "eventId": "a962df6d-2ea8-4dff-8a68-d49b1dc74d33",
      "projectId": null,
      "credits": 5000,
      "eventType": "allocation",
      "format": null,
      "containerId": null,
      "workflowId": null,
      "balanceAfterPrepaid": 5400,
      "usageAfterPeriod": null,
      "createdAt": "2026-06-03T18:14:02.187Z"
    },
    {
      "eventId": "1133c79a-e49e-4e52-81e7-ac13ef77d72a",
      "projectId": "prj_13fd8406-387a-4472-b6a2-531860557a6e",
      "credits": -50,
      "eventType": "usage",
      "format": "slideshow-builder",
      "containerId": "cnt_a861adb5-3a48-48a4-a18d-c70129ebefa7",
      "workflowId": "partner-content-a861adb5-...-v0",
      "balanceAfterPrepaid": 5350,
      "usageAfterPeriod": 3000,
      "createdAt": "2026-06-03T19:02:41.004Z"
    }
  ],
  "nextCursor": null
}

Event types

Type	Sign of `credits`	When
`usage`	always negative	The child's content-generation charge.
`refund`	always positive	Automatic refund when a paid generation fails post-charge, or an admin reversal.
`grant`	always positive	Free credits granted to the child by Layers.
`purchase`	always positive	Prepaid pack purchased via Stripe.
`adjustment`	either sign	Admin manual adjustment; direction is on the sign of `credits`.
`allocation`	positive here	A parent→child transfer. On the child's ledger an allocation is positive (credited). The matching debit appears on the parent's own /v1/credits/events. `metadata.direction` is `allocate` or `reclaim`; `metadata.counterpartyOrgId` (`org_`-prefixed) names the other side, and `metadata.transferId` (`txn_`-prefixed) matches the `id` the allocate response returns, so you can join the two ledgers. Any `description` / `metadata` you passed to allocate is echoed here too (your keys sit alongside the reserved system keys, which win on collision).

Field notes

credits is signed - debits negative, credits positive. Sum them for a wallet-level reconciliation.
projectId is null for org-level events (grants, purchases, allocations). Filtering by projectId excludes those rows by design.
balanceAfterPrepaid / usageAfterPeriod are reconciliation breadcrumbs - the wallet state right after this event. null when the event didn't touch that side.
Ordered newest first; the cursor is opaque - pass it back verbatim.

Errors

Status	Code	When
404	`NOT_FOUND`	`:orgId` is not a direct child of your org (anti-enumeration).
422	`VALIDATION`	Malformed `:orgId`, a bad `projectId`, a non-`Z` timestamp, or an invalid `eventType` / `limit`.
503	`KILL_SWITCH`	Your key or org is suspended; or the child org is suspended/archived.