# GET /v1/organizations/:orgId/credits/events (/docs/api/reference/organizations/credits/list-events)



<Endpoint method="GET" path="/v1/organizations/{orgId}/credits/events" auth="Bearer" scope="org:admin" phase="1" />

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`](/docs/api/reference/credits/list-events), scoped to the child named in the path.

This is where parent→child funding shows up: every [allocation](/docs/api/reference/organizations/credits/allocate) lands here as an `allocation` event (positive on the child you funded), so the ledger reconciles the wallet you see in [GET …/credits](/docs/api/reference/organizations/credits/get-credits).

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

## Query parameters [#query-parameters]

<Parameters
  rows="[
  { name: 'projectId', type: 'string', description: '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.' },
  { name: 'eventType', type: 'string', enum: ['usage', 'refund', 'grant', 'purchase', 'adjustment', 'allocation'], description: 'Filter to one event type. See &#x22;Event types&#x22; below.' },
  { name: 'since', type: 'string (ISO 8601 Z)', description: 'Only events `>= since`. UTC required (Z suffix; offset form like +00:00 is rejected).' },
  { name: 'until', type: 'string (ISO 8601 Z)', description: 'Only events `<= until`. UTC required (Z suffix).' },
  { name: 'cursor', type: 'string', description: 'Opaque cursor from the previous page.' },
  { name: 'limit', type: 'integer', default: '25', description: 'Page size, 1-100.' },
]"
/>

## Example [#example]

```bash
# 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"
```

<Response status="200" description="OK">
  ```json
  {
    "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
  }
  ```
</Response>

### Event types [#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](/docs/api/reference/credits/list-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](/docs/api/reference/organizations/credits/allocate) response returns, so you can join the two ledgers. Any `description` / `metadata` you passed to [allocate](/docs/api/reference/organizations/credits/allocate) is echoed here too (your keys sit alongside the reserved system keys, which win on collision). |

### Field notes [#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 [#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.                            |

## See also [#see-also]

* [Child wallet](/docs/api/reference/organizations/credits/get-credits) - the balance these events reconcile to.
* [Allocate credits](/docs/api/reference/organizations/credits/allocate) - what creates `allocation` events.
* [GET /v1/credits/events](/docs/api/reference/credits/list-events) - your own ledger (the parent side of each allocation).