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 Status is where the work is: Planned (in a milestone, not started), Building (tickets in progress), Preview (usable, may change), then the stability it ships at.
Stability The promise an interface ships with.
- Stable Follows semantic versioning; breaking changes need a new major, 12 months of overlap and a codemod.
- Beta Usable in production; may change before it becomes stable.
- Experimental May change or go away; needs an explicit opt-in in main.yaml.
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.yamland a GitHub remote.
1. Sign in
npx mainsdk login --region euThe 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
npx mainsdk keys create --env prodThis 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
npx mainsdk usageGET /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
npx mainsdk logoutSending stops at once; every check keeps working locally.
Was this page helpful?