# List instances

`GET https://app.shuttleglobal.com/c/api/instances`

Performs a search against instance objects with optional filtering, sorting, and pagination.

## Authentication

- basicAuth: Basic Authentication using secret key

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `criteria` | query | string | no | The search criteria (URL encoded). Available fields: application, client, contact_email, contact_name, contact_phone, created, domain, id, last_contract, last_transaction, name, status, updated Supports the following operators: - `=`: Exact match, separate multiple values with `;` for IN operation - `!=`: Not equal - `>=`, `>`, `<`, `<=`: Greater than/equal, less than/equal - `~=`: Partial match (case insensitive) - `<>`: Between, separate values with `;` (e.g., `<>min;max`) - `!`: Is null - `!!`: Is not null Separate multiple criteria with commas (`,`) Notes: - Strings are case insensitive (with some exceptions) - Booleans are Y/N (TIP: check for `=Y` or `!=Y` as some objects treat false as null) Examples: - `status=ACTIVE;FAILING` (status is either ACTIVE or FAILING) - `status=ACTIVE;FAILING,email=dave@gmail.com` (status is ACTIVE or FAILING AND email is dave@gmail.com) - `name~=Test` (name contains 'Test') - `created<>2023-01-01;2023-12-31` (created between Jan 1 and Dec 31, 2023) - `scheduler=Y` (scheduler is enabled) |
| `order` | query | string | no | The sort order to apply. Format: `field[:desc][,field2[:desc]]` - Supports any field that criteria supports - Defaults to created:desc if not specified - Will order ascending unless you specify desc - Separate multiple order fields with commas Examples: - order=updated (sort by updated ascending) - order=updated:desc (sort by updated descending) - order=status,updated:desc (sort by status ascending, then updated descending) |
| `expand` | query | string | no | Fields to expand into full objects |
| `limit` | query | integer | no | Number of records to return: 20 if not set, at most 1000. |
| `offset` | query | integer | no | Number of records to skip before the first one returned. `offset` + `limit` can't exceed 5000; to read further, page by a field such as `created` instead. See [Paging through results](/platforms/reference/paging/). |

## Responses

### 200: Successful operation

```json
{
  "instances": [
    {
      "id": "string",
      "name": "string",
      "instance_key": "string",
      "status": "ACTIVATING",
      "application": "string",
      "checkout_urls": [
        "string"
      ],
      "client": "string",
      "contact_email": "string",
      "contact_name": "string",
      "contact_phone": "string",
      "country": "string",
      "created": "2026-01-01T12:00:00Z",
      "domain": "string",
      "domains": [
        "string"
      ],
      "environment": "SANDBOX",
      "features": [
        "string"
      ],
      "last_contract": "2026-01-01T12:00:00Z",
      "last_transaction": "2026-01-01T12:00:00Z",
      "merchant_name": "string",
      "metadata": {},
      "parent": "string",
      "private_integrations": [
        "string"
      ],
      "processors": [
        "string"
      ],
      "receipt_format": "string",
      "receipt_users": [
        "string"
      ],
      "report_users": [
        "string"
      ],
      "retry_error_schedule": [
        0
      ],
      "retry_schedule": [
        0
      ],
      "secret_key": "string",
      "tcs_accepted": "2026-01-01T12:00:00Z",
      "tcs_accepted_user": "string",
      "tcs_outstanding": true,
      "terminated": "2026-01-01T12:00:00Z",
      "updated": "2026-01-01T12:00:00Z",
      "v": 0,
      "webhook_target": "string"
    }
  ],
  "meta": {
    "limit": 0,
    "offset": 0,
    "total": 0
  }
}
```

### 400: Bad request

```json
{
  "code": "string",
  "message": "string"
}
```

### 401: Unauthorized

```json
{
  "code": "UNAUTHORIZED",
  "message": "Unauthorised"
}
```

## Example request

```sh
curl --request GET \
  --url https://app.shuttleglobal.com/c/api/instances \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>'
```

Reference page: https://docs.shuttleglobal.com/platforms/reference/platform/operations/listinstances/