API

grid.ip.list

From GoGrid



Contents

This call will list the IPs available to in your grid. This method follows a common list pattern but has added filter capabilities. With filtering you can see all, unassigned, public, or private IPs.

Request

URL


Role Based Access Control Permissions

  • Super User
  • System User
  • Billing User
  • Read Only User

Data Center-Specific Behavior

IP addresses in the US-West-1 data center are assigned to you automatically when your GoGrid account is created. IP addresses in US-East-1 are dynamically assigned; these IP addresses will automatically be allocated when you either add a cloud server via the customer portal or make a grid.ip.list call with datacenter set to US-East-1 (see the next section).

To access data center functionality, you must set your version parameter (v) to 1.5 or higher.

Input Request Query Parameters

Required Name Version Type Description
Required api_key 1.0 string An API Key generated by GoGrid.
  sig 1.0 string An MD5 Signature that signs each and every API request. Instructions on how to generate this signature can be found here.
v 1.0 string The version of the API. For more information, see API Versions.
  • For version 1.3, set parameter to 1.3
 
Optional num_items 1.0 int The number of items to return. Specifying this value will effectively paginate the results of a list call into a number of pages with this number of items per page. This makes it easier and faster to access large lists. If not specified, result will not be paginated.
  page 1.0 int The page index to return for paginated results, indexed from 0, so a value of 0 will return the first available page, 1 will return the second page and so forth. This parameter is ignored if num_items is not specified.
  ip.state 1.1 string The state to filter on. int or string representing the state option's id or name respectively.
  • If no value is set for this parameter, all states will be included in the query.
  • To list ip.state values, call common.lookup.list with lookup set to ip.state
  ip.type 1.1 string The type to filter on. int or string representing the type option's id or name respectively.
  • If no value is set for this parameter, all types will be included in the query.
  • To list ip.type values, call common.lookup.list with lookup set to ip.type
  datacenter 1.5 string The datacenter to filter on. int or string representing the datacenter option's id or name respectively.
  • If no value is set for this parameter, all IPs will be included in the query. See section above for instructions on allocating US-East-1 IPs.
  • Multiple values are accepted
  • Default is empty, therefore all included.
  • To list datacenter values, call common.lookup.list with lookup set to ip.datacenter
format 1.0 string The output format of the response. For more information, see Output Formats.
  • For JSON, set parameter to json.
  • For XML, set parameter to xml.
  • For CSV, set parameter to csv.
  • Default is json.

Sample Request

To list unassigned, public IPs: 

https://api.gogrid.com/api/grid/ip/list
  ?id=203923
  &ip.state=Unassigned
  &ip.type=Public
  ... auth parameters...


Response


A common list response , filtered to return unassigned public IPs.

JSON Response

{
    "list": [
        {
            "datacenter": {
                "description": "US West 1 Datacenter",
                "id": 1,
                "name": "US-West-1",
                "object": "option"
            },
            "id": 65669,
            "ip": "208.113.110.132",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is available to use",
                "id": 1,
                "name": "Unassigned",
                "object": "option"
            },
            "subnet": "208.113.110.128/255.255.255.240"
        },
        {
            "datacenter": {
                "description": "US West 1 Datacenter",
                "id": 1,
                "name": "US-West-1",
                "object": "option"
            },
            "id": 65670,
            "ip": "208.113.110.133",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is available to use",
                "id": 1,
                "name": "Unassigned",
                "object": "option"
            },
            "subnet": "208.113.110.128/255.255.255.240"
        },
        {
            "datacenter": {
                "description": "US West 1 Datacenter",
                "id": 1,
                "name": "US-West-1",
                "object": "option"
            },
            "id": 65674,
            "ip": "208.113.110.137",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is available to use",
                "id": 1,
                "name": "Unassigned",
                "object": "option"
            },
            "subnet": "208.113.110.128/255.255.255.240"
        },
        {
            "datacenter": {
                "description": "US West 1 Datacenter",
                "id": 1,
                "name": "US-West-1",
                "object": "option"
            },
            "id": 65675,
            "ip": "208.113.110.138",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is available to use",
                "id": 1,
                "name": "Unassigned",
                "object": "option"
            },
            "subnet": "208.113.110.128/255.255.255.240"
        },
        {
            "datacenter": {
                "description": "US West 1 Datacenter",
                "id": 1,
                "name": "US-West-1",
                "object": "option"
            },
            "id": 65676,
            "ip": "208.113.110.139",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is available to use",
                "id": 1,
                "name": "Unassigned",
                "object": "option"
            },
            "subnet": "208.113.110.128/255.255.255.240"
        },
        {
            "datacenter": {
                "description": "US West 1 Datacenter",
                "id": 1,
                "name": "US-West-1",
                "object": "option"
            },
            "id": 65677,
            "ip": "208.113.110.140",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is available to use",
                "id": 1,
                "name": "Unassigned",
                "object": "option"
            },
            "subnet": "208.113.110.128/255.255.255.240"
        },
        {
            "datacenter": {
                "description": "US West 1 Datacenter",
                "id": 1,
                "name": "US-West-1",
                "object": "option"
            },
            "id": 65678,
            "ip": "208.113.110.141",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is available to use",
                "id": 1,
                "name": "Unassigned",
                "object": "option"
            },
            "subnet": "208.113.110.128/255.255.255.240"
        },
        {
            "datacenter": {
                "description": "US West 1 Datacenter",
                "id": 1,
                "name": "US-West-1",
                "object": "option"
            },
            "id": 65679,
            "ip": "208.113.110.142",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is available to use",
                "id": 1,
                "name": "Unassigned",
                "object": "option"
            },
            "subnet": "208.113.110.128/255.255.255.240"
        },
        {
            "datacenter": {
                "description": "US East 1 Datacenter",
                "id": 2,
                "name": "US-East-1",
                "object": "option"
            },
            "id": 232315,
            "ip": "204.51.198.74",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is available to use",
                "id": 1,
                "name": "Unassigned",
                "object": "option"
            },
            "subnet": "204.51.198.64/255.255.255.240"
        },
        {
            "datacenter": {
                "description": "US East 1 Datacenter",
                "id": 2,
                "name": "US-East-1",
                "object": "option"
            },
            "id": 232316,
            "ip": "204.51.198.75",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is available to use",
                "id": 1,
                "name": "Unassigned",
                "object": "option"
            },
            "subnet": "204.51.198.64/255.255.255.240"
        },
        {
            "datacenter": {
                "description": "US East 1 Datacenter",
                "id": 2,
                "name": "US-East-1",
                "object": "option"
            },
            "id": 232317,
            "ip": "204.51.198.76",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is available to use",
                "id": 1,
                "name": "Unassigned",
                "object": "option"
            },
            "subnet": "204.51.198.64/255.255.255.240"
        },
        {
            "datacenter": {
                "description": "US East 1 Datacenter",
                "id": 2,
                "name": "US-East-1",
                "object": "option"
            },
            "id": 232318,
            "ip": "204.51.198.77",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is available to use",
                "id": 1,
                "name": "Unassigned",
                "object": "option"
            },
            "subnet": "204.51.198.64/255.255.255.240"
        },
        {
            "datacenter": {
                "description": "US East 1 Datacenter",
                "id": 2,
                "name": "US-East-1",
                "object": "option"
            },
            "id": 232319,
            "ip": "204.51.198.78",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is available to use",
                "id": 1,
                "name": "Unassigned",
                "object": "option"
            },
            "subnet": "204.51.198.64/255.255.255.240"
        }
    ],
    "method": "/grid/ip/list",
    "status": "success",
    "summary": {
        "numpages": 0,
        "returned": 13,
        "start": 0,
        "total": 13
    }
}

XML Response

<gogrid>
  <response method="/grid/ip/list" status="success">
    <summary total="13" start="0" numpages="0" returned="13"/>
    <list>
      <object name="ip">
        <attribute name="id">65669</attribute>
        <attribute name="ip">208.113.110.132</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">208.113.110.128/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">US-West-1</attribute>
            <attribute name="description">US West 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
      <object name="ip">
        <attribute name="id">65670</attribute>
        <attribute name="ip">208.113.110.133</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">208.113.110.128/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">US-West-1</attribute>
            <attribute name="description">US West 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
      <object name="ip">
        <attribute name="id">65674</attribute>
        <attribute name="ip">208.113.110.137</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">208.113.110.128/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">US-West-1</attribute>
            <attribute name="description">US West 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
      <object name="ip">
        <attribute name="id">65675</attribute>
        <attribute name="ip">208.113.110.138</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">208.113.110.128/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">US-West-1</attribute>
            <attribute name="description">US West 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
      <object name="ip">
        <attribute name="id">65676</attribute>
        <attribute name="ip">208.113.110.139</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">208.113.110.128/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">US-West-1</attribute>
            <attribute name="description">US West 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
      <object name="ip">
        <attribute name="id">65677</attribute>
        <attribute name="ip">208.113.110.140</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">208.113.110.128/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">US-West-1</attribute>
            <attribute name="description">US West 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
      <object name="ip">
        <attribute name="id">65678</attribute>
        <attribute name="ip">208.113.110.141</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">208.113.110.128/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">US-West-1</attribute>
            <attribute name="description">US West 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
      <object name="ip">
        <attribute name="id">65679</attribute>
        <attribute name="ip">208.113.110.142</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">208.113.110.128/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">US-West-1</attribute>
            <attribute name="description">US West 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
      <object name="ip">
        <attribute name="id">232315</attribute>
        <attribute name="ip">204.51.198.74</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">204.51.198.64/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">2</attribute>
            <attribute name="name">US-East-1</attribute>
            <attribute name="description">US East 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
      <object name="ip">
        <attribute name="id">232316</attribute>
        <attribute name="ip">204.51.198.75</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">204.51.198.64/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">2</attribute>
            <attribute name="name">US-East-1</attribute>
            <attribute name="description">US East 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
      <object name="ip">
        <attribute name="id">232317</attribute>
        <attribute name="ip">204.51.198.76</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">204.51.198.64/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">2</attribute>
            <attribute name="name">US-East-1</attribute>
            <attribute name="description">US East 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
      <object name="ip">
        <attribute name="id">232318</attribute>
        <attribute name="ip">204.51.198.77</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">204.51.198.64/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">2</attribute>
            <attribute name="name">US-East-1</attribute>
            <attribute name="description">US East 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
      <object name="ip">
        <attribute name="id">232319</attribute>
        <attribute name="ip">204.51.198.78</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">204.51.198.64/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">2</attribute>
            <attribute name="name">US-East-1</attribute>
            <attribute name="description">US East 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
    </list>
  </response>
</gogrid>

CSV Response

# SUCCESS, /grid/ip/list, TOTAL, 13, NUMPAGES, 0, START, 0, RETURNED, 13
# id,ip,state.id,state.name,state.description,subnet,public,datacenter.id,datacenter.name,datacenter.description
65669,208.113.110.132,1,Unassigned,IP is available to use,208.113.110.128/255.255.255.240,true,1,US-West-1,US West 1 Datacenter
65670,208.113.110.133,1,Unassigned,IP is available to use,208.113.110.128/255.255.255.240,true,1,US-West-1,US West 1 Datacenter
65674,208.113.110.137,1,Unassigned,IP is available to use,208.113.110.128/255.255.255.240,true,1,US-West-1,US West 1 Datacenter
65675,208.113.110.138,1,Unassigned,IP is available to use,208.113.110.128/255.255.255.240,true,1,US-West-1,US West 1 Datacenter
65676,208.113.110.139,1,Unassigned,IP is available to use,208.113.110.128/255.255.255.240,true,1,US-West-1,US West 1 Datacenter
65677,208.113.110.140,1,Unassigned,IP is available to use,208.113.110.128/255.255.255.240,true,1,US-West-1,US West 1 Datacenter
65678,208.113.110.141,1,Unassigned,IP is available to use,208.113.110.128/255.255.255.240,true,1,US-West-1,US West 1 Datacenter
65679,208.113.110.142,1,Unassigned,IP is available to use,208.113.110.128/255.255.255.240,true,1,US-West-1,US West 1 Datacenter
232315,204.51.198.74,1,Unassigned,IP is available to use,204.51.198.64/255.255.255.240,true,2,US-East-1,US East 1 Datacenter
232316,204.51.198.75,1,Unassigned,IP is available to use,204.51.198.64/255.255.255.240,true,2,US-East-1,US East 1 Datacenter
232317,204.51.198.76,1,Unassigned,IP is available to use,204.51.198.64/255.255.255.240,true,2,US-East-1,US East 1 Datacenter
232318,204.51.198.77,1,Unassigned,IP is available to use,204.51.198.64/255.255.255.240,true,2,US-East-1,US East 1 Datacenter
232319,204.51.198.78,1,Unassigned,IP is available to use,204.51.198.64/255.255.255.240,true,2,US-East-1,US East 1 Datacenter

Error Codes

Status Code Description
400 IllegalArgumentException Any problems with input parameters will generate an IllegalArgumentException.
401 Unauthorized This error code will occur when the role tied to the API Key in your request has the wrong Access Controls.
403 Authentication Failed This error code will occur when your request is not properly signed. Make sure your have a valid API key and secret and that you are properly generating a request signature. Ensure that the clock on the computer from which you are making the request is synchronized woth the GoGrid API Server.
404 Not Found This error will occur if you have specified a method that does not exist or any other URL does not exists on the API Server.
500 UnexpectedError These types of errors indicate an internal system problem. Depending on the severity of the error and whether not it is blocking your development, report the error to GoGrid support by emailing the response to apisupport@gogrid.com.
Retrieved from "http://wiki.gogrid.com/wiki/index.php/API:grid.ip.list"
Personal tools