# GET /v1/organizations/:orgId (/docs/api/reference/organizations/get-organization)



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

Fetch one child organization by id, with a small `summary` block (project count and wallet balances) for dashboards. `:orgId` must be a direct child of your org — anything else returns `404 NOT_FOUND` (we don't leak existence with a `403`).

<Parameters
  title="Path"
  rows="[
  { name: 'orgId', type: 'string', required: true, description: 'The child org id (`org_`-prefixed or bare UUID).' },
]"
/>

## Example request [#example-request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    curl https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80 \
      -H "Authorization: Bearer $PARENT_KEY"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    const org = await fetch(
      "https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80",
      { headers: { "Authorization": `Bearer ${process.env.PARENT_KEY}` } },
    ).then((r) => r.json());
    ```
  </Tab>

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

    org = requests.get(
        "https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80",
        headers={"Authorization": f"Bearer {os.environ['PARENT_KEY']}"},
    ).json()
    ```
  </Tab>
</Tabs>

## Response [#response]

<Response status="200" description="OK">
  ```json
  {
    "id": "org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80",
    "parentOrganizationId": "org_2481fa5c-a404-44ed-a561-565392499abc",
    "name": "Acme Coffee",
    "status": "active",
    "metadata": { "externalId": "acme-coffee", "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",
    "summary": {
      "projectCount": 3,
      "balance": 5000,
      "available": 4880,
      "creditConfig": {
        "monthlyCreditCap": 5000,
        "refillThreshold": 1000,
        "refillAmount": 2000,
        "autoRefillEnabled": true
      }
    }
  }
  ```
</Response>

### Field notes [#field-notes]

* `summary.projectCount` is the number of projects under the child org.
* `summary.balance` is the child's gross wallet (`includedRemaining + prepaidBalance`) at call time. `summary.available` is that balance net of credits reserved for in-flight generations — gate the child's "can they generate?" decision on `available`. Both mirror the child wallet endpoint, [`GET /v1/organizations/:orgId/credits`](/docs/api/reference/organizations/credits/get-credits). A freshly created child reads `0` for both until its wallet is [funded](/docs/api/reference/organizations/credits/allocate).
* `summary.creditConfig` is the child's spend governance — `monthlyCreditCap`, `refillThreshold`, `refillAmount` (all in credits, nullable) and the derived `autoRefillEnabled`. Set it with [`PATCH /v1/organizations/:orgId/credit-config`](/docs/api/reference/organizations/credit-config); a freshly created child reads all-null / `autoRefillEnabled: false`.
* `summary` appears only on this single-org endpoint, not on the [list](/docs/api/reference/organizations/list-organizations).

## Errors [#errors]

| Status | Code              | When                                                          |
| ------ | ----------------- | ------------------------------------------------------------- |
| 404    | `NOT_FOUND`       | No such org, or it isn't a direct child of your org.          |
| 422    | `VALIDATION`      | The `:orgId` is not a valid organization id (malformed UUID). |
| 401    | `UNAUTHENTICATED` | Missing or invalid key.                                       |
| 403    | `FORBIDDEN_SCOPE` | Key lacks `org:admin`.                                        |
| 429    | `RATE_LIMITED`    | Read budget exhausted.                                        |

## See also [#see-also]

* [`PATCH /v1/organizations/:orgId`](/docs/api/reference/organizations/patch-organization) — update name / metadata.
* [`GET /v1/organizations`](/docs/api/reference/organizations/list-organizations) — list all children.