# Instances

## List instances in a session[​](#list-instances "Direct link to List instances in a session")

GET/api/v1/sessions/{sessionId}/instances

Instances attached to the session, newest first. Visible to every member of the organization that owns the session.

Path parameters

`sessionId`string · uuidrequired

Session UUID

Header parameters

`X-Organization-Id`string

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

`object`stringrequired

`data`arrayrequired

Show child attributes

`id`string · uuidrequired

The instance's own id

`status`stringrequired

Lifecycle: provisioning -> ready, then released, or failed if provisioning could not complete

`os`stringrequired

Instance operating system. Only macos is supported today.

`image`stringrequired

Server-assigned base image the instance booted from

`machine`objectrequired

The compute backing an instance.

Show child attributes

`arch`stringrequired

CPU architecture. Only arm64 is supported today.

`cpuCores`integerrequired

`memoryMb`integerrequired

`diskMb`integerrequired

`createdAt`string · date-timerequired

When the instance was allocated (billing start)

`readyAt`string · date-timenullable

When the instance finished provisioning; null while provisioning

`releasedAt`string · date-timenullable

When the instance was released (billing end); null while active

`nextCursor`stringnullable

Cursor for the next page; absent when there are no more results

Request

```
curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/instances \

  -X GET \

  -H 'Authorization: Bearer mob_...'
```

Response

200401403404

Instances attached to the session

```
{

  "object": "list",

  "data": [

    {

      "id": "string",

      "status": "provisioning",

      "os": "macos",

      "image": "macos-15-xcode-16",

      "machine": {

        "arch": "arm64",

        "cpuCores": 8,

        "memoryMb": 16384,

        "diskMb": 262144

      },

      "createdAt": "2026-01-01T00:00:00Z",

      "readyAt": "2026-01-01T00:00:00Z",

      "releasedAt": "2026-01-01T00:00:00Z"

    }

  ],

  "nextCursor": "string"

}
```

## Allocate an instance[​](#create-instance "Direct link to Allocate an instance")

POST/api/v1/sessions/{sessionId}/instances

Allocates a new instance (a build/automation machine) attached to the session. Provisioning is asynchronous: the instance is returned immediately with status "provisioning" and becomes usable once its status is "ready". Poll GET /sessions/{sessionId}/instances/{instanceId} to observe readiness.

Path parameters

`sessionId`string · uuidrequired

Session UUID

Header parameters

`X-Organization-Id`string

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Body parameters

`os`stringrequired

Instance operating system. Only macos is supported today.

Returns

A build/automation machine allocated to a session.

`id`string · uuidrequired

The instance's own id

`status`stringrequired

Lifecycle: provisioning -> ready, then released, or failed if provisioning could not complete

`os`stringrequired

Instance operating system. Only macos is supported today.

`image`stringrequired

Server-assigned base image the instance booted from

`machine`objectrequired

The compute backing an instance.

Show child attributes

`arch`stringrequired

CPU architecture. Only arm64 is supported today.

`cpuCores`integerrequired

`memoryMb`integerrequired

`diskMb`integerrequired

`createdAt`string · date-timerequired

When the instance was allocated (billing start)

`readyAt`string · date-timenullable

When the instance finished provisioning; null while provisioning

`releasedAt`string · date-timenullable

When the instance was released (billing end); null while active

Request

```
curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/instances \

  -X POST \

  -H 'Authorization: Bearer mob_...' \

  -H 'Content-Type: application/json' \

  -d '{"os":"macos"}'
```

Response

201400401403404409

Instance allocated; provisioning has started

```
{

  "id": "string",

  "status": "provisioning",

  "os": "macos",

  "image": "macos-15-xcode-16",

  "machine": {

    "arch": "arm64",

    "cpuCores": 8,

    "memoryMb": 16384,

    "diskMb": 262144

  },

  "createdAt": "2026-01-01T00:00:00Z",

  "readyAt": "2026-01-01T00:00:00Z",

  "releasedAt": "2026-01-01T00:00:00Z"

}
```

## Get an instance[​](#get-instance "Direct link to Get an instance")

GET/api/v1/sessions/{sessionId}/instances/{instanceId}

Returns an instance attached to the session. Visible to every member of the organization that owns the session.

Path parameters

`sessionId`string · uuidrequired

Session UUID

`instanceId`string · uuidrequired

Instance UUID

Header parameters

`X-Organization-Id`string

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

A build/automation machine allocated to a session.

`id`string · uuidrequired

The instance's own id

`status`stringrequired

Lifecycle: provisioning -> ready, then released, or failed if provisioning could not complete

`os`stringrequired

Instance operating system. Only macos is supported today.

`image`stringrequired

Server-assigned base image the instance booted from

`machine`objectrequired

The compute backing an instance.

Show child attributes

`arch`stringrequired

CPU architecture. Only arm64 is supported today.

`cpuCores`integerrequired

`memoryMb`integerrequired

`diskMb`integerrequired

`createdAt`string · date-timerequired

When the instance was allocated (billing start)

`readyAt`string · date-timenullable

When the instance finished provisioning; null while provisioning

`releasedAt`string · date-timenullable

When the instance was released (billing end); null while active

Request

```
curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/instances/{instanceId} \

  -X GET \

  -H 'Authorization: Bearer mob_...'
```

Response

200401403404

Instance detail

```
{

  "id": "string",

  "status": "provisioning",

  "os": "macos",

  "image": "macos-15-xcode-16",

  "machine": {

    "arch": "arm64",

    "cpuCores": 8,

    "memoryMb": 16384,

    "diskMb": 262144

  },

  "createdAt": "2026-01-01T00:00:00Z",

  "readyAt": "2026-01-01T00:00:00Z",

  "releasedAt": "2026-01-01T00:00:00Z"

}
```

## Release an instance[​](#release-instance "Direct link to Release an instance")

POST/api/v1/sessions/{sessionId}/instances/{instanceId}/release

Releases an instance, stopping billing and tearing it down. Returns the instance with its updated status. Idempotent: releasing an already-released instance is a no-op.

Path parameters

`sessionId`string · uuidrequired

Session UUID

`instanceId`string · uuidrequired

Instance UUID

Header parameters

`X-Organization-Id`string

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

A build/automation machine allocated to a session.

`id`string · uuidrequired

The instance's own id

`status`stringrequired

Lifecycle: provisioning -> ready, then released, or failed if provisioning could not complete

`os`stringrequired

Instance operating system. Only macos is supported today.

`image`stringrequired

Server-assigned base image the instance booted from

`machine`objectrequired

The compute backing an instance.

Show child attributes

`arch`stringrequired

CPU architecture. Only arm64 is supported today.

`cpuCores`integerrequired

`memoryMb`integerrequired

`diskMb`integerrequired

`createdAt`string · date-timerequired

When the instance was allocated (billing start)

`readyAt`string · date-timenullable

When the instance finished provisioning; null while provisioning

`releasedAt`string · date-timenullable

When the instance was released (billing end); null while active

Request

```
curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/instances/{instanceId}/release \

  -X POST \

  -H 'Authorization: Bearer mob_...'
```

Response

202401403404

Release accepted; teardown proceeds asynchronously

```
{

  "id": "string",

  "status": "provisioning",

  "os": "macos",

  "image": "macos-15-xcode-16",

  "machine": {

    "arch": "arm64",

    "cpuCores": 8,

    "memoryMb": 16384,

    "diskMb": 262144

  },

  "createdAt": "2026-01-01T00:00:00Z",

  "readyAt": "2026-01-01T00:00:00Z",

  "releasedAt": "2026-01-01T00:00:00Z"

}
```