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

# GET /v1/numbers — List & Detail

> GET /v1/numbers — Returns all WhatsApp numbers connected to your Pilot Status project, including their status, type, and unique identifiers.

# List and inspect numbers

List every WhatsApp number in your account, or fetch the full detail of one number — including health and, for Meta numbers, live data from the Meta Graph.

<Note>
  Use a **tenant-scoped** API key to manage numbers across your account. A number-scoped key can also call these endpoints. Authenticate with the `x-api-key: ps_...` header.
</Note>

## GET /v1/numbers — List all numbers

Lists all WhatsApp instances for the API key's **tenant** as a JSON array.

* Does **not** return session credentials.
* Each number exposes its flat connection `state` and an `isFullyConnected` flag.
* The list does **not** force a mass refresh of connection state — use `GET /v1/numbers/{id}/status` per number when you need a live check.
* Each item's `apiKeys` entries include only `name`, `keyPrefix`, and `keyLast4` (no API key `id`).

```bash theme={null}
curl "https://pilotstatus.com.br/v1/numbers" \
  -H "x-api-key: ps_your_token_here"
```

## GET /v1/numbers/{id} — Full detail of one number

Returns the flat `state`/`isFullyConnected`, a `health` block (`qualityRating`, `messagingLimitTier`, `metaStatus`, `sendable`), and — for **Meta** numbers — a nested camelCase `meta` block with `phone`, `profile`, and `waba` info pulled from the Meta Graph. For non-Meta numbers `meta` is `null`.

<ParamField query="refresh" type="string">
  Add `?refresh=1` to force a live Meta Graph fetch and persist the snapshot. By default the response is cached (last `meta` snapshot).
</ParamField>

Secrets (access tokens, app secret, provider config) are **never** returned. Returns `404` if the id is not in the caller's tenant.

```bash theme={null}
# 1) list to get the id
curl "https://pilotstatus.com.br/v1/numbers" \
  -H "x-api-key: ps_your_token_here"

# 2) fetch full detail of one number (add ?refresh=1 to pull live from the Meta Graph)
curl "https://pilotstatus.com.br/v1/numbers/wa_abc?refresh=1" \
  -H "x-api-key: ps_your_token_here"
```

Response (Meta number):

```json theme={null}
{
  "id": "wa_abc",
  "number": "5511999999999",
  "name": "My WhatsApp",
  "provider": "META",
  "state": "OPEN",
  "isFullyConnected": true,
  "createdAt": "2026-02-24T15:00:00.000Z",
  "updatedAt": "2026-06-30T09:18:33.000Z",
  "health": {
    "qualityRating": "GREEN",
    "messagingLimitTier": "TIER_2K",
    "metaStatus": "CONNECTED",
    "sendable": true
  },
  "meta": {
    "fetchedAt": "2026-06-30T09:18:33.000Z",
    "phone": {
      "displayPhoneNumber": "+55 11 99999-9999",
      "verifiedName": "Acme LTDA",
      "qualityRating": "GREEN",
      "messagingLimitTier": "TIER_2K",
      "isPinEnabled": true
    },
    "profile": {
      "about": "8h-18h",
      "email": "contato@acme.com",
      "websites": ["https://acme.com"],
      "vertical": "RETAIL"
    },
    "waba": {
      "id": "1029384756",
      "name": "Acme WABA",
      "currency": "BRL",
      "businessVerificationStatus": "verified",
      "country": "BR"
    }
  }
}
```

For a non-Meta (unofficial / QR) number the same call returns `"provider": "PILOT_STATUS"` and `"meta": null`.