# GET /v1/organizations (/docs/api/reference/organizations/list-organizations)



<Endpoint method="GET" path="/v1/organizations" auth="Bearer" scope="org:admin" phase="1" />

List the child organizations under your org, newest first. Cursor-paginated and filterable by `status`. Only your own direct children are returned — never another partner's orgs.

<Parameters
  title="Query"
  rows="[
  { name: 'status', type: 'string', description: 'Filter to one lifecycle state.', enum: ['active', 'suspended', 'archived'] },
  { name: 'limit', type: 'integer', description: 'Page size. 1–200.', default: '25' },
  { name: 'cursor', type: 'string', description: 'Opaque cursor from a prior response\'s `nextCursor`. Omit for the first page.' },
]"
/>

## Example request [#example-request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    curl "https://api.layers.com/v1/organizations?status=active&limit=25" \
      -H "Authorization: Bearer $PARENT_KEY"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    const page = await fetch(
      "https://api.layers.com/v1/organizations?status=active&limit=25",
      { headers: { "Authorization": `Bearer ${process.env.PARENT_KEY}` } },
    ).then((r) => r.json());

    // Next page:
    if (page.nextCursor) {
      await fetch(
        `https://api.layers.com/v1/organizations?cursor=${encodeURIComponent(page.nextCursor)}`,
        { headers: { "Authorization": `Bearer ${process.env.PARENT_KEY}` } },
      );
    }
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import os, requests

    page = requests.get(
        "https://api.layers.com/v1/organizations",
        headers={"Authorization": f"Bearer {os.environ['PARENT_KEY']}"},
        params={"status": "active", "limit": 25},
    ).json()
    ```
  </Tab>
</Tabs>

## Response [#response]

<Response status="200" description="OK">
  ```json
  {
    "items": [
      {
        "id": "org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80",
        "parentOrganizationId": "org_2481fa5c-a404-44ed-a561-565392499abc",
        "name": "Acme Coffee",
        "status": "active",
        "metadata": { "externalId": "cust_12345", "plan": "growth" },
        "billingEmail": "ops@acme.example",
        "archivedAt": null,
        "createdAt": "2026-06-01T14:30:00.000000+00:00",
        "updatedAt": "2026-06-01T14:30:00.000000+00:00"
      }
    ],
    "nextCursor": null
  }
  ```
</Response>

### Field notes [#field-notes]

* `items` is ordered newest-first by creation time.
* `nextCursor` is `null` on the last page. When present, pass it back as `?cursor=` to fetch the next page. Treat it as opaque — don't parse it.
* The list returns the same org shape as [create](/docs/api/reference/organizations/create-organization), without the per-org `summary` block (call [`GET /v1/organizations/:orgId`](/docs/api/reference/organizations/get-organization) for that).

## Errors [#errors]

| Status | Code              | When                                                          |
| ------ | ----------------- | ------------------------------------------------------------- |
| 401    | `UNAUTHENTICATED` | Missing or invalid key.                                       |
| 403    | `FORBIDDEN_SCOPE` | Key lacks `org:admin`.                                        |
| 422    | `VALIDATION`      | `limit` out of range, or `status` not one of the enum values. |
| 429    | `RATE_LIMITED`    | Read budget exhausted.                                        |

## See also [#see-also]

* [`POST /v1/organizations`](/docs/api/reference/organizations/create-organization) — create a child org.
* [`GET /v1/organizations/:orgId`](/docs/api/reference/organizations/get-organization) — a single child with summary stats.