---
title: "Use MainSDK Cloud, usage and billing"
description: "Sign in from the device flow, send events with an ingest key, read your usage, add a card with a cap, and understand grace and the 402 answer."
section: "guides"
status: "Planned for 0.6"
spec: "usage-billing"
canonical: "https://mainsdk.dev/docs/guides/cloud-login-usage-and-billing"
updated: "2026-10-28"
---

# Use MainSDK Cloud, usage and billing

> Sign in from the device flow, send events with an ingest key, read your usage, add a card with a cap, and understand grace and the 402 answer.

Status: Planned for 0.6 · Canonical: https://mainsdk.dev/docs/guides/cloud-login-usage-and-billing · Updated: 2026-10-28

You will sign in, send events from CI, check what you have used, and set a monthly cap. It takes about 10 minutes.

## You need

- A MainSDK app with a project id in `main.yaml` and a GitHub remote.

## 1. Sign in

```bash
npx mainsdk login --region eu
```

The command shows a short code and an address; you never type or paste a key. For a copy or a fork, `npx mainsdk init --new-id` gives it a fresh project id first. Nothing is sent before you log in. Underneath, the device flow (RFC 8628) starts at `POST /v1/device/code` with your project and remote. Approve the user code in the console with a passkey, then poll `POST /v1/device/token`. A project id already claimed under another remote answers `MAIN-CLOUD-0009`; choose a new id.

## 2. Send events

```bash
npx mainsdk keys create --env prod
```

This creates an ingest key for an environment (`/v1/projects/{id}/keys`). Keys start with `msk_live_` or `msk_test_` and are shown once. CI can send with its OIDC token instead of a key. A project is pinned to one region; another region answers 421 with `MAIN-CLOUD-0001`.

Set `telemetry: { sample, budget }` in `main.yaml` to cap what the SDK sends. It samples what it stores, never what it enforces.

## 3. Read your usage

```bash
npx mainsdk usage
```

`GET /v1/usage` returns the month's events, the share of the allowance, the days of grace left and your cap. Free proposes 50,000 events a month and 7 days of history. You get one warning at 80%.

## 4. Past the allowance

With no card, events continue to 120% or 7 days, whichever comes first, then the Cloud answers 402 (`MAIN-CLOUD-0402`) with a link to the card page. Your app keeps running: nothing inside it is metered, so nothing inside it is blocked.

With a card (`npx mainsdk billing card --cap 50` opens the card page; `POST /v1/billing/card` takes the monthly cap), events past the allowance are billed per 100,000 up to the cap, and hosted reviewer runs are priced per run. At the cap the same 402 applies. One-time add-ons go through `POST /v1/addons` and are charged once.

Prices and the allowance are proposals until the owner sets them.

## 5. Sign out

```bash
npx mainsdk logout
```

Sending stops at once; every check keeps working locally.