---
title: "Request carrier launch"
method: POST
path: "/v1/agents/{id}/request-launch"
tags: ["Google & carriers"]
---

# Request carrier launch

`POST /v1/agents/{id}/request-launch`

## Request

- Base URL: `https://api.cadencercs.com`
- URL: `https://api.cadencercs.com/v1/agents/{id}/request-launch`
- Auth: HTTP bearer

**This is what makes an agent reach non-test devices.** Reachability is carrier-scoped, so an agent launched on two carriers is invisible on a third.

`carriers` replaces the whole launch set at Google rather than adding to it — previously requested carriers are re-sent automatically, because omitting them would silently drop those launches while the request still succeeded.

Verification must have been *submitted* first, but it only *completes* during launch approval: requiring `verified` here would deadlock, since verification never starts until a launch exists.

## Path parameters

- `id` string, required

## Request body

- object
  - `carriers` string[], required: Carrier names, e.g. `["T-Mobile","AT&T"]`. See `GET /v1/carriers`.
  - `confirm` 'irreversible'

## Response `200`

Accepted by Google.

- object
  - `ok` boolean, required
  - `status` 'launching', required
  - `carriers` string[], required: The complete launch set now on file.
  - `carriedForward` string[]: Previously requested carriers re-sent to avoid dropping them.
  - `note` string
  - `nextStep` string
  - `warning` string: Google accepted the launch but our own records could not be updated. **Do not retry** — poll `GET /v1/agents/{id}/launch` for the authoritative state.
  - `bookkeepingErrors` string[]

## Other responses

- `400`: `carriers` is required.
- `401`: Not signed in, and no account-linked API key was sent.
- `404`: No such agent on this account.
- `409`: Not confirmed (`CONFIRMATION_REQUIRED`), verification never submitted (`VERIFICATION_NOT_SUBMITTED`), or the questionnaire is incomplete (`QUESTIONNAIRE_INCOMPLETE`). Nothing happened.
- `500`: Unexpected server error. The body is always JSON.
- `502`: Google rejected the request.
- `503`: RBM not configured.

---

[API](https://skmtc.dev/cadencercs/apis/cadence-api.md) · [All operations](https://skmtc.dev/cadencercs/apis/cadence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cadencercs/apis/cadence-api/revisions/9438443c2081?raw)