---
title: "Get a line's connection status"
method: GET
path: "/v1/numbers/{numberId}/connection"
tags: ["Numbers"]
---

# Get a line's connection status

`GET /v1/numbers/{numberId}/connection`

## Request

- Base URL: `https://api.telgea.com`
- URL: `https://api.telgea.com/v1/numbers/{numberId}/connection`
- Auth: API key in header `x-api-key`

Reads what the network reports about one line: its status there (active, suspended or inactive), when it last saw activity on the line, the country and operator the line is attached to, the network type, and the IP address, APN and device IMEI in use.

**A line is read at most once per 5-minute window.** The windows are fixed, starting on the clock's 5-minute marks rather than at a request. A request inside a window gets the answer the network gave at `checkedAt`, whoever asked first, without the network being asked again — so polling more often returns the same answer. The first request in the next window reads the line again, however recent the last read. A failed read is answered again the same way until its window ends. Reads of many lines are answered a few at a time per network, so a loop over a large roster takes a while.

Some lines cannot be read: those in a market whose network does not report connection status, those with no phone number or eSIM yet, and those still being ported in or already ended. They answer `200` with `available: false` and every other field null.

A line in another organization answers exactly as one that does not exist.

## Path parameters

- `numberId` string, uuid, required: UUID of the line.

## Response `200`

The line's connection status, or `available: false` for a line that cannot be read.

- NumberConnection: What the line's network reports about it.
  - `available` boolean, required: Whether the line's network could be asked. False for a line in a market whose network does not report connection status, one with no phone number or eSIM yet, and one still being ported in or already ended; every other field is then null.
  - `status` 'active' | 'suspended' | 'inactive' | 'unknown' | 'null', nullable, required: How the network holds the line: `active`, `suspended` or `inactive`, or `unknown` when the network does not say.
  - `lastSeenAt` string, nullable, required: When the network last saw activity on the line, as an ISO 8601 UTC time. Null when the network does not report it.
  - `countryCode` string, nullable, required: The country the line is attached in, ISO 3166-1 alpha-2. Null when the network does not report it.
  - `servingNetwork` string, nullable, required: The name of the network operator serving the line. Null when the network does not report it.
  - `accessTechnology` '2G' | '3G' | '4G' | '5G' | 'unknown' | 'null', nullable, required: The network type the line is attached on, or `unknown` when the network does not say.
  - `ipAddress` string, nullable, required: The IP address the line holds for data. Null when the network does not report it.
  - `apn` string, nullable, required: The access point name the line uses for data. Null when the network does not report it.
  - `imei` string, nullable, required: The IMEI of the device the line was last seen in. Null when the network does not report it.
  - `checkedAt` string, nullable, required: When the network was asked, as an ISO 8601 UTC time. A read is shared for the rest of its 5-minute window, so this can be up to 5 minutes earlier than your request.

## Other responses

- `400`: Request failed schema validation, or was refused by a business rule
- `401`: Missing or invalid API key in the X-API-Key header
- `403`: Insufficient permissions to read lines
- `404`: No line in your organization has this id.
- `429`: The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.
- `500`: Internal server error. Contact support if this persists.
- `503`: The network serving this line did not answer, so its connection status could not be read.

---

[API](https://skmtc.dev/telgea/apis/telgea-api.md) - [All operations](https://skmtc.dev/telgea/apis/telgea-api/llms.txt) - [OpenAPI document](https://skmtc.dev/telgea/apis/telgea-api/revisions/4e8f8c04fe9e?raw)