> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Numbers

> Give your agent a phone number for sending and receiving SMS.

Part of the [Identity stack](https://docs.mobilerun.ai/identity/overview.md): an API-first, plug-and-play SMS layer for your agent's phone.

Cloud Numbers are phone numbers for SMS. Use a number for app verification and text conversations
alongside your agent phone. Availability, included capacity, and sending capabilities depend on the number.

## Countries

| Country | Stock (Nov 2026) |
| - | - |
| 🇦🇺 Australia | Available |
| 🇦🇹 Austria | Out of stock |
| 🇨🇦 Canada | Out of stock |
| 🇨🇿 Czechia | Out of stock |
| 🇩🇪 Germany | Available |
| 🇭🇰 Hong Kong SAR China | Available |
| 🇮🇱 Israel | Out of stock |
| 🇮🇹 Italy | Out of stock |
| 🇲🇽 Mexico | Out of stock |
| 🇳🇱 Netherlands | Available |
| 🇵🇹 Portugal | Out of stock |
| 🇸🇪 Sweden | Out of stock |
| 🇨🇭 Switzerland | Out of stock |
| 🇺🇦 Ukraine | Out of stock |
| 🇬🇧 United Kingdom | Available |
| 🇺🇸 United States | Available |

Stock changes. Call `numbers.countries()` for live availability
(see the [SDK example below](#get-a-number)).

## Get a number

Open the numbers section of the [dashboard](https://cloud.mobilerun.ai), choose an available country,
and follow the checkout flow if payment is required. With the [SDK](https://docs.mobilerun.ai/guides/sdk-objects.md), set
`MOBILERUN_API_KEY` and check the catalog and capacity first:

```typescript TypeScript theme={null}
import { MobilerunSDK } from '@mobilerun/sdk';

const mobilerun = new MobilerunSDK(); // Reads MOBILERUN_API_KEY.

console.log(await mobilerun.numbers.countries());
console.log(await mobilerun.numbers.capacity({ country: 'de' }));
```

```python Python theme={null}
from mobilerun_sdk import MobilerunSDK

mobilerun = MobilerunSDK()  # Reads MOBILERUN_API_KEY.

print(mobilerun.numbers.countries())
print(mobilerun.numbers.capacity(country="de"))
```

> [!WARNING]
>
> `numbers.create` starts a number rental and can incur charges. Capacity is advisory; creation decides
> whether included capacity is available. `included` uses included capacity with paid fallback,
> `included_only` requires an included slot, and `rent` starts paid checkout.

The following purchase example is separate from the read-only catalog calls:

```typescript TypeScript theme={null}
import { MobilerunSDK } from '@mobilerun/sdk';

const mobilerun = new MobilerunSDK(); // Reads MOBILERUN_API_KEY.

const number = await mobilerun.numbers.create({ country: 'de', billingPreference: 'included' });
await number.refresh();
if (number.state === 'awaiting_payment') {
  console.log(number.info); // data.checkoutUrl: complete checkout before waiting.
} else {
  await number.waitUntilActive();
  console.log(number.phoneNumber);
}
```

```python Python theme={null}
from mobilerun_sdk import MobilerunSDK

mobilerun = MobilerunSDK()  # Reads MOBILERUN_API_KEY.

number = mobilerun.numbers.create(country="de", billing_preference="included")
number.refresh()
if number.state == "awaiting_payment":
    print(number.info)  # data.checkout_url: complete checkout before waiting.
else:
    number.wait_until_active()
    print(number.phone_number)
```

`waitUntilActive()` (Python `wait_until_active()`) polls provisioning. It fails for `awaiting_payment`,
`failed`, or `expired`; the wait error carries the last response, including `data.checkoutUrl`
(Python `data.checkout_url`) when checkout is needed.

## Use it with a phone

Enter the number in the app running on your [phone](https://docs.mobilerun.ai/devices.md), then read the incoming verification SMS
through the SDK. Keep the same number for that account's future sign-ins. Sending an SMS is a separate
operation and requires the number to support the destination and message length.

The next example sends a real SMS when you run it. Replace the recipient with a number you control.

```typescript TypeScript theme={null}
import { MobilerunSDK } from '@mobilerun/sdk';

const mobilerun = new MobilerunSDK(); // Reads MOBILERUN_API_KEY.

const number = mobilerun.numbers.fromId('NUMBER_ID');
const message = await number.send({ to: '+12025550123', body: 'Hello from my agent' });
console.log(message.id, message.status);
```

```python Python theme={null}
from mobilerun_sdk import MobilerunSDK

mobilerun = MobilerunSDK()  # Reads MOBILERUN_API_KEY.

number = mobilerun.numbers.from_id("NUMBER_ID")
message = number.send(to="+12025550123", body="Hello from my agent")
print(message.id, message.status)
```

## Read results

List messages across your numbers or group them into conversations. Use message direction and status
to distinguish incoming messages from outgoing send attempts; a sent status does not promise delivery.

```typescript TypeScript theme={null}
import { MobilerunSDK } from '@mobilerun/sdk';

const mobilerun = new MobilerunSDK(); // Reads MOBILERUN_API_KEY.

console.log(await mobilerun.api.messages.list());
console.log(await mobilerun.api.messages.conversations.list());
```

```python Python theme={null}
from mobilerun_sdk import MobilerunSDK

mobilerun = MobilerunSDK()  # Reads MOBILERUN_API_KEY.

print(mobilerun.api.messages.list())
print(mobilerun.api.messages.conversations.list())
```

## Costs and cancellation

Check current pricing in the dashboard before renting. Included slots depend on your plan and country;
paid rentals require checkout. Cancel a pending purchase or schedule cancellation of an active paid number:

```typescript TypeScript theme={null}
import { MobilerunSDK } from '@mobilerun/sdk';

const mobilerun = new MobilerunSDK(); // Reads MOBILERUN_API_KEY.

await mobilerun.numbers.fromId('NUMBER_ID').delete();
```

```python Python theme={null}
from mobilerun_sdk import MobilerunSDK

mobilerun = MobilerunSDK()  # Reads MOBILERUN_API_KEY.

mobilerun.numbers.from_id("NUMBER_ID").delete()
```

Repeating a scheduled cancellation is safe. A `409` response means cancellation is not available.

## API reference

See [Numbers](https://docs.mobilerun.ai/api-reference/numbers/list-phone-numbers.md) for the catalog, capacity, rental states,
and cancellation, plus its message and conversation endpoints.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.