GET /v2/list-phone-numbers – Retell AI Retell SDK

List phone numbers with pagination

get/v2/list-phone-numbers

Query parameters

limitinteger

Maximum number of items to return.

sort_order'ascending' | 'descending'

Sort order for results.

pagination_keystring

Pagination key for fetching the next page.

Response

Successfully retrieved phone numbers.

pagination_keystring

Pagination key for the next page.

has_moreboolean

Whether more results are available.

Example response

{
  "items": [
    {
      "phone_number": "+14157774444",
      "phone_number_type": "retell-twilio",
      "phone_number_pretty": "+1 (415) 777-4444",
      "allowed_inbound_country_list": [
        "US",
        "CA",
        "GB"
      ],
      "allowed_outbound_country_list": [
        "US",
        "CA"
      ],
      "area_code": 415,
      "inbound_agents": [
        {
          "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
          "agent_version": 1,
          "weight": 0.5
        }
      ],
      "outbound_agents": [
        {
          "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
          "agent_version": 1,
          "weight": 0.5
        }
      ],
      "inbound_sms_agents": [
        {
          "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
          "agent_version": 1,
          "weight": 0.5
        }
      ],
      "outbound_sms_agents": [
        {
          "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
          "agent_version": 1,
          "weight": 0.5
        }
      ],
      "nickname": "Frontdesk Number",
      "inbound_webhook_url": "https://example.com/inbound-webhook",
      "inbound_sms_webhook_url": "https://example.com/inbound-sms-webhook",
      "last_modification_timestamp": 1703413636133,
      "sip_outbound_trunk_config": {
        "termination_uri": "someuri.pstn.twilio.com",
        "auth_username": "username",
        "transport": "TCP"
      },
      "fallback_number": "+14155551234"
    }
  ]
}

Changes

Changed in 5 of the 28 revisions of this API.449

May 28, 202640402ca870b94See the full diff
- ○
  the ////// response's property pattern was changed from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the ////// response's property pattern was changed from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the ////// response's property pattern was changed from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the ////// response's property pattern was changed from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
May 8, 20267dd16ddf69d84See the full diff
- ○
  the ////// response's property pattern was changed from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the ////// response's property pattern was changed from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the ////// response's property pattern was changed from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the ////// response's property pattern was changed from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
May 7, 2026f1a0d7c1e36c4See the full diff
- ▲
  response property allOf[subschema #2]/items/items/inbound_agents/items/agent_version list-of-types was widened by adding types string to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property allOf[subschema #2]/items/items/inbound_sms_agents/items/agent_version list-of-types was widened by adding types string to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property allOf[subschema #2]/items/items/outbound_agents/items/agent_version list-of-types was widened by adding types string to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property allOf[subschema #2]/items/items/outbound_sms_agents/items/agent_version list-of-types was widened by adding types string to media type application/json of response 200
  response-property-list-of-types-widened
Apr 20, 20268ee53928bf314See the full diff
- ●
  removed the optional property /// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property /// from the response with the status
  response-optional-property-removed
Feb 23, 2026bcff6899fa2a1See the full diff
- ○
  endpoint added
  endpoint-added

Full history