GET /v1/organizations

GET/v1/organizations

Phase 1stable

Auth: Bearer
Scope: org:admin

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.

Query

status
stringoptional
Filter to one lifecycle state.
One of: active, suspended, archived
limit
integeroptionaldefault: 25
Page size. 1–200.
cursor
stringoptional
Opaque cursor from a prior response's `nextCursor`. Omit for the first page.

Example request

curl "https://api.layers.com/v1/organizations?status=active&limit=25" \
  -H "Authorization: Bearer $PARENT_KEY"

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}` } },
  );
}

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()

Response

200OK

{
  "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
}

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, without the per-org summary block (call GET /v1/organizations/:orgId for that).

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.

Example request

Response

Field notes

Errors

See also

On this page