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

# List Calling Numbers

> Discover your account's owned caller IDs for programmable voice.

Returns caller IDs owned by the authenticated account, including eligible assigned and managed calling numbers. Requires the `voice_calls.read` scope and the **Voice Calls** product entitlement.

Inventory confirms ownership. Call placement still checks backend readiness, billing, compliance, and other admission requirements. Provision programmable voice numbers in [Calling](https://app.tracklysms.com/voice/calling).

The `/v1/voice/numbers` route belongs to the separate SIP-trunking product. [Who Am I](/api-reference/v2/auth/whoami) links to this inventory through `voice.calling_numbers_url`; its `api_key.send_policy.list_numbers` field describes SMS sending-list restrictions, where an empty array means unrestricted by list policy.

## Query Parameters

Only `limit` and `cursor` are accepted, each at most once.

<ParamField query="limit" type="integer" default={20}>
  Maximum candidate numbers scanned for this page, from `1` to `100`. Filtering can return fewer items, including an empty page with a continuation cursor.
</ParamField>

<ParamField query="cursor" type="string" optional>
  Pass the previous response's `nextCursor` unchanged. Cursors belong to the authenticated account. Continue until `nextCursor` is `null`, even when `items` is empty.
</ParamField>

## Response Fields

<ResponseField name="items" type="array">
  Owned caller IDs on this page.

  <Expandable title="Calling number properties" defaultOpen>
    <ResponseField name="items[].id" type="string">The calling-number assignment's identifier.</ResponseField>
    <ResponseField name="items[].e164" type="string">The caller ID in E.164 format, including its leading `+`. Use this value as `from` when placing a call.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextCursor" type="string | null">
  Opaque continuation token, or `null` when no candidate numbers remain.
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.tracklysms.com/api/v1/voice/calling-numbers?limit=20" \
    -H "X-Api-Key: trk_your_api_key_here"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "items": [
      {
        "id": "665f1e2a9c4b1a0012ab34cd",
        "e164": "+18005551234"
      }
    ],
    "nextCursor": null
  }
  ```
</ResponseExample>

## Error Codes

| Status | Code                           | Meaning                                                                                                                                                |
| ------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 403    | `insufficient_scope`           | The API key lacks `voice_calls.read`.                                                                                                                  |
| 403    | `voice_not_entitled`           | Voice calling is not enabled for your account.                                                                                                         |
| 422    | `invalid_fields`               | A query parameter is unsupported or repeated.                                                                                                          |
| 422    | `invalid_limit`                | `limit` is not an integer from `1` to `100`.                                                                                                           |
| 422    | `invalid_cursor`               | The cursor is invalid or its anchor is no longer present in your account.                                                                              |
| 503    | `number_inventory_unavailable` | Registry authority needed to verify managed-number ownership is unavailable. Retry later; this error does not mean the account has no calling numbers. |