# List and search organizations

> The platform.organizations.list operation: GET /api/v1/platform/organizations in the REST API and the platform_organizations_list tool in the MCP server.

Lists the organizations on Ownrecord, newest first, for platform staff (spec §39.1). `query` matches an
organization ID exactly, the start of a slug, part of a name, or (with an `@`) a member's email address; `status`
filters on `active`, `restricted`, `suspended`, `closing` or `closed`.

Each organization comes with metadata only (spec §39.2): name, slug, country, status, support-access policy, the
plan read from the platform brand (`plan.key` from the subscription's prices; `internal` for the platform
organization) with the plan cache's status, and counts of entities, brands (live ones too) and members. Its
customers, invoices, ledger and settings need a support-access grant.

## At a glance

- **REST:** `GET /api/v1/platform/organizations`
- **MCP tool:** `platform_organizations_list`
- **Operation ID:** `platform.organizations.list`
- **Scope:** Platform
- **Permission:** `platform:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Pagination:** `limit` (at most 100) and `starting_after`
- **Authentication:** API key with the `platform:read` scope
- **Since:** M12

## Request

### Query parameters

| Field            | Type                                                            | Required | Description                                                                     |
| ---------------- | --------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------- |
| `query`          | string                                                          | No       | An organization ID, a slug prefix, part of a name, or a member's email address. |
| `status`         | one of `active`, `restricted`, `suspended`, `closing`, `closed` | No       | Only organizations with this status.                                            |
| `limit`          | integer (1 to 100)                                              | No       | Page size, 1 to 100 (default 10).                                               |
| `starting_after` | `org_…` ID                                                      | No       | The `next_cursor` of the previous page.                                         |

## Response

`200 OK` with a JSON object, a page of the list (newest first):

| Field                          | Type                                                                  | Description                                                                 |
| ------------------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `object`                       | `"list"`                                                              |                                                                             |
| `data`                         | array of object                                                       |                                                                             |
| `data[].object`                | `"platform_organization"`                                             |                                                                             |
| `data[].id`                    | `org_…` ID                                                            |                                                                             |
| `data[].slug`                  | string                                                                |                                                                             |
| `data[].name`                  | string                                                                |                                                                             |
| `data[].country`               | string                                                                |                                                                             |
| `data[].status`                | one of `active`, `restricted`, `suspended`, `closing`, `closed`       |                                                                             |
| `data[].statusReason`          | string or null                                                        |                                                                             |
| `data[].isPlatform`            | boolean                                                               |                                                                             |
| `data[].supportAccess`         | one of `off`, `on_request`, `always_read`                             |                                                                             |
| `data[].plan`                  | object                                                                |                                                                             |
| `data[].plan.key`              | string or null                                                        | The plan (plans.yaml key), read from the platform brand; null when unknown. |
| `data[].plan.name`             | string or null                                                        |                                                                             |
| `data[].plan.source`           | one of `subscription`, `internal`, `none`                             |                                                                             |
| `data[].plan.status`           | one of `trialing`, `active`, `past_due`, `unpaid`, `canceled`, `none` | The plan cache's subscription status (spec §37.4).                          |
| `data[].plan.currentPeriodEnd` | date-time or null                                                     |                                                                             |
| `data[].plan.override`         | boolean                                                               | Whether a plan override is active.                                          |
| `data[].counts`                | object                                                                |                                                                             |
| `data[].counts.entities`       | integer                                                               |                                                                             |
| `data[].counts.brands`         | integer                                                               |                                                                             |
| `data[].counts.liveBrands`     | integer                                                               |                                                                             |
| `data[].counts.members`        | integer                                                               |                                                                             |
| `data[].createdAt`             | date-time                                                             |                                                                             |
| `has_more`                     | boolean                                                               |                                                                             |
| `next_cursor`                  | `org_…` ID or null                                                    |                                                                             |

## Examples

### Find an organization by name

```http
GET /api/v1/platform/organizations?query=acme
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "list",
  "data": [
    {
      "object": "platform_organization",
      "id": "org_01m5wvkry1e6w94sjxgme33fs5",
      "slug": "acme",
      "name": "Acme",
      "country": "HR",
      "status": "active",
      "statusReason": null,
      "isPlatform": false,
      "supportAccess": "on_request",
      "plan": {
        "key": "growth",
        "name": "Growth",
        "source": "subscription",
        "status": "active",
        "currentPeriodEnd": "2026-11-14T10:02:11.000Z",
        "override": false
      },
      "counts": {
        "entities": 1,
        "brands": 2,
        "liveBrands": 1,
        "members": 6
      },
      "createdAt": "2026-09-14T10:02:11.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

| Code                                                                                   | HTTP status | When                                                                | What to do                                                                      |
| -------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400         | A filter or pagination value is invalid.                            | Fix the fields listed in `details.issues` and send the request again.           |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403         | You aren't platform staff with read access to the platform console. | Ask an organization owner or admin for a role or scope that allows this action. |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).