# List instances

> List the instances accessible within an organization.

`GET /api/organizations/{organizationId}/instances`

List instances accessible within an organization.

Returns the paginated collection of instances accessible to the authenticated partner within an organization. Filter by `name` or `handle`, and order by any of the listed fields.

## Path parameters

| Name             | Type     | Required | Description                              |
| ---------------- | -------- | -------- | ---------------------------------------- |
| `organizationId` | `string` | Yes      | OrganizationInstancesResource identifier |

## Query parameters

| Name               | Type      | Required | Description                                                                                                      |
| ------------------ | --------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `name`             | `string`  | -        | Partial case-insensitive search on the instance name. Combined as AND with `handle` when both are provided.      |
| `handle`           | `string`  | -        | Partial case-insensitive search on the instance handle. Combined as AND with `name` when both are provided.      |
| `order[name]`      | `string`  | -        | Sort by name. Values: asc, desc.                                                                                 |
| `order[handle]`    | `string`  | -        | Sort by handle. Values: asc, desc.                                                                               |
| `order[createdAt]` | `string`  | -        | Sort by creation date. Values: asc, desc. Default order when no `order` parameter is provided: `createdAt` desc. |
| `order[updatedAt]` | `string`  | -        | Sort by last update date. Values: asc, desc.                                                                     |
| `page`             | `integer` | -        | The collection page number                                                                                       |
| `itemsPerPage`     | `integer` | -        | The number of items per page                                                                                     |

## Response

**200** - OrganizationInstancesResource collection

| Property     | Type                              | Required | Description |
| ------------ | --------------------------------- | -------- | ----------- |
| `totalItems` | `integer`                         | -        |             |
| `search`     | `object`                          | -        |             |
| `view`       | `object`                          | -        |             |
| `member`     | `OrganizationInstancesResource[]` | Yes      |             |

## Errors

**403** - Forbidden

| Property   | Type             | Required | Description                                                                                                                          |
| ---------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `@context` | `object`         | -        |                                                                                                                                      |
| `@id`      | `string`         | Yes      |                                                                                                                                      |
| `@type`    | `string`         | Yes      |                                                                                                                                      |
| `title`    | `string \| null` | -        | A short, human-readable summary of the problem.                                                                                      |
| `detail`   | `string \| null` | -        | A human-readable explanation specific to this occurrence of the problem.                                                             |
| `status`   | `number \| null` | -        |                                                                                                                                      |
| `instance` | `string \| null` | -        | A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. |
| `type`     | `string`         | -        | A URI reference that identifies the problem type                                                                                     |

## Examples

### Example request

```bash
curl -X GET 'https://identity.flowkiwi.net/api/organizations/<organization_id>/instances' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/ld+json'
```

### Example response

```json
{
  "totalItems": 0,
  "search": {
    "@type": "string",
    "template": "string",
    "variableRepresentation": "string",
    "mapping": [
      {
        "@type": "string",
        "variable": "string",
        "property": "string",
        "required": true
      }
    ]
  },
  "view": {
    "@id": "string",
    "@type": "string",
    "first": "string",
    "last": "string",
    "previous": "string",
    "next": "string"
  },
  "member": [
    {
      "@context": "string",
      "@id": "string",
      "@type": "OrganizationInstancesResource",
      "id": "0196f3a0-3333-7000-8000-000000000001",
      "name": "Acme EU",
      "handle": "acme-eu",
      "created_at": "2026-01-16T10:00:00+00:00",
      "updated_at": "2026-01-21T08:45:00+00:00",
      "organization_id": "0196f3a0-1111-7000-8000-000000000001",
      "created_by_organization_id": "0196f3a0-1111-7000-8000-000000000001"
    }
  ]
}
```