# Sessions

## List sessions[​](#list-sessions "Direct link to List sessions")

GET/api/v1/sessions

Sessions in the selected organization, visible to every member of it, newest first, with cursor pagination. The organization is chosen by the X-Organization-Id header, or the organization the API key is bound to, otherwise the caller's default organization.

Query parameters

`limit`integer

Maximum sessions to return (default 100, max 500)

`before`string · date-time

Cursor: return sessions created strictly before this RFC3339 timestamp

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 session's own id

`title`stringnullable

Human-readable title; may be null

`user`stringrequired

User who created this session

`devices`arrayrequired

Device allocations linked to this session, ordered by createdAt ascending

Show child attributes

`id`string · uuidrequired

Allocation id. Stable and always present, including while the device is still provisioning and no physical device exists yet. This is not the device's own id — see info.serial.

`status`stringrequired

Device lifecycle status. \`provisioning\` means a device is being booted and has no info.serial yet; \`in\_use\` means it is allocated and driveable; \`released\` means it has been returned to the pool. More values will be added.

`info`objectrequired

Descriptive attributes of the device.

Show child attributes

`platform`stringrequired

`type`string

`name`stringrequired

`osVersion`stringrequired

`serial`string

The physical device's own id — a UDID on iOS, a serial on Android. Absent while the device is provisioning. This is the id accepted by the device endpoints and tools.

`createdAt`string · date-timerequired

When the device was added to the session

`releasedAt`string · date-timenullable

When the device was released (billing end)

`instances`array

Instances linked to this session, ordered by createdAt ascending

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

`chats`array

Chats in this session, oldest first. A client restoring a session's conversation reads the last one.

Show child attributes

`id`stringrequired

Chat id

`createdAt`string · date-timerequired

`nextCursor`stringnullable

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

Request

```
curl https://api.mobilenext.ai/api/v1/sessions \

  -X GET \

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

Response

200400401403

Paginated list of sessions

```
{

  "object": "list",

  "data": [

    {

      "id": "string",

      "title": "string",

      "user": "string",

      "devices": [

        {

          "id": "string",

          "status": "provisioning",

          "info": {

            "platform": "ios",

            "type": "real",

            "name": "string",

            "osVersion": "string",

            "serial": "00008150-001C30842678401C"

          },

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

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

        }

      ],

      "instances": [

        {

          "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"

        }

      ],

      "chats": [

        {

          "id": "string"

        }

      ],

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

    }

  ],

  "nextCursor": "string"

}
```

## Create a session[​](#create-session "Direct link to Create a session")

POST/api/v1/sessions

Creates an empty session container. Attach resources to it separately: use fleet.allocate with sessionId to link a device, or allocate an instance with sessionId.

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

`id`string · uuidrequired

The session's own id

`title`stringnullable

Human-readable title; may be null

`user`stringrequired

User who created this session

`devices`arrayrequired

Device allocations linked to this session, ordered by createdAt ascending

Show child attributes

`id`string · uuidrequired

Allocation id. Stable and always present, including while the device is still provisioning and no physical device exists yet. This is not the device's own id — see info.serial.

`status`stringrequired

Device lifecycle status. \`provisioning\` means a device is being booted and has no info.serial yet; \`in\_use\` means it is allocated and driveable; \`released\` means it has been returned to the pool. More values will be added.

`info`objectrequired

Descriptive attributes of the device.

Show child attributes

`platform`stringrequired

`type`string

`name`stringrequired

`osVersion`stringrequired

`serial`string

The physical device's own id — a UDID on iOS, a serial on Android. Absent while the device is provisioning. This is the id accepted by the device endpoints and tools.

`createdAt`string · date-timerequired

When the device was added to the session

`releasedAt`string · date-timenullable

When the device was released (billing end)

`instances`array

Instances linked to this session, ordered by createdAt ascending

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

`chats`array

Chats in this session, oldest first. A client restoring a session's conversation reads the last one.

Show child attributes

`id`stringrequired

Chat id

`createdAt`string · date-timerequired

Request

```
curl https://api.mobilenext.ai/api/v1/sessions \

  -X POST \

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

Response

201401403

Session created

```
{

  "id": "string",

  "title": "string",

  "user": "string",

  "devices": [

    {

      "id": "string",

      "status": "provisioning",

      "info": {

        "platform": "ios",

        "type": "real",

        "name": "string",

        "osVersion": "string",

        "serial": "00008150-001C30842678401C"

      },

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

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

    }

  ],

  "instances": [

    {

      "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"

    }

  ],

  "chats": [

    {

      "id": "string"

    }

  ],

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

}
```

## Get a session[​](#get-session "Direct link to Get a session")

GET/api/v1/sessions/{sessionId}

Returns a session in the selected organization, visible to every member of it. The organization is chosen by the X-Organization-Id header, or the organization the API key is bound to, otherwise the caller's default organization.

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

`id`string · uuidrequired

The session's own id

`title`stringnullable

Human-readable title; may be null

`user`stringrequired

User who created this session

`devices`arrayrequired

Device allocations linked to this session, ordered by createdAt ascending

Show child attributes

`id`string · uuidrequired

Allocation id. Stable and always present, including while the device is still provisioning and no physical device exists yet. This is not the device's own id — see info.serial.

`status`stringrequired

Device lifecycle status. \`provisioning\` means a device is being booted and has no info.serial yet; \`in\_use\` means it is allocated and driveable; \`released\` means it has been returned to the pool. More values will be added.

`info`objectrequired

Descriptive attributes of the device.

Show child attributes

`platform`stringrequired

`type`string

`name`stringrequired

`osVersion`stringrequired

`serial`string

The physical device's own id — a UDID on iOS, a serial on Android. Absent while the device is provisioning. This is the id accepted by the device endpoints and tools.

`createdAt`string · date-timerequired

When the device was added to the session

`releasedAt`string · date-timenullable

When the device was released (billing end)

`instances`array

Instances linked to this session, ordered by createdAt ascending

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

`chats`array

Chats in this session, oldest first. A client restoring a session's conversation reads the last one.

Show child attributes

`id`stringrequired

Chat id

`createdAt`string · date-timerequired

Request

```
curl https://api.mobilenext.ai/api/v1/sessions/{sessionId} \

  -X GET \

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

Response

200401403404

Session detail

```
{

  "id": "string",

  "title": "string",

  "user": "string",

  "devices": [

    {

      "id": "string",

      "status": "provisioning",

      "info": {

        "platform": "ios",

        "type": "real",

        "name": "string",

        "osVersion": "string",

        "serial": "00008150-001C30842678401C"

      },

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

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

    }

  ],

  "instances": [

    {

      "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"

    }

  ],

  "chats": [

    {

      "id": "string"

    }

  ],

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

}
```