Contents

This call will list all the jobs in the system for a specified date range. The default is the last month. This method follows a common list pattern.


Request

URL


Role Based Access Control Permissions

  • Super User
  • System User

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.7, set the parameter to 1.7.
 
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. This will default to 100 items for all list methods.
  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.
  startdate 1.0 datetime The start date of the filtered date range.
  • For input rules, see datetime inputs.
  • The default is the calculation representing four weeks ago.
  enddate 1.0 datetime The end date of the filtered date range.
  job.objecttype 1.0 string The object type to filter on. int or string representing the job object type option's ID or name, respectively.
  • If no value is set for this parameter, all object types will be included in the query.
  • Multiple values are accepted.
  • The default is empty, therefore all are included.
  job.state 1.0 string The job state to filter on. int or string representing the job state option's ID or name, respectively.
  • If no value is set for this parameter, all job state types will be included in the query.
  • Multiple values are accepted.
  • The default is empty, therefore all are included.
  owner 1.0 string The owner to filter on. Filter is case insensitive, and matches partial strings (e/g joe matches joe@gogrid.com).
  • If no value is set, all users will be included in the query.
  • Multiple values are accepted.
  • The default is empty, therefore all are included.
  object 1.0 string The object name to filter on. If this parameter is provided all other filter parameters will be ignored.
  datacenter 1.5 string The data center to filter on. int or string representing the data center option's ID or name, respectively.
  • If no value is set for this parameter, all jobs will be included in the query.
  • Multiple values are accepted.
  • The default is empty, therefore all are included.
  • To list datacenter values, call common.lookup.list with lookup set to job.datacenter.

Sample Request

To list all jobs in the last month:

https://api.gogrid.com/api/grid/job/list?
  api_key=6f8b9155cb25149c&
  sig=06b7bafbf43f5a69f741ea8996abdb81&
  startdate=03%2F01%2F2009&
  enddate=03%2F31%2F2009&
  job.state=Succeeded&
  job.objecttype=VirtualServer&
  datacenter=US-West-1&
  v=1.5&
  format=xml



Response

A common list response of Jobs. The list is a list of all jobs in the system for the input date range.

JSON Response

{
    "list": [
        {
            "attempts": 1,
            "command": {
                "description": "Create Virtual Server",
                "id": 6,
                "name": "CreateVirtualServer",
                "object": "option"
            },
            "createdon": 1231007644632,
            "currentstate": {
                "description": "Change request has succeeded.",
                "id": 3,
                "name": "Succeeded",
                "object": "option"
            },
            "datacenter": {
                "description": "US East 1 Datacenter",
                "id": 2,
                "name": "US-East-1",
                "object": "option"
            },
            "detail": {
                "description": "tests",
                "image": "w2k3_64_iis_asp_mssql2k5xp",
                "ip": "208.113.76.34",
                "name": "test 2",
                "type": "virtual_server"
            },
            "history": [
                {
                    "id": 10242,
                    "state": {
                        "description": "Change request is created but not queued yet",
                        "id": 7,
                        "name": "Created",
                        "object": "option"
                    }
                },
                {
                    "id": 10243,
                    "state": {
                        "description": "Change request is new to the system.",
                        "id": 1,
                        "name": "Queued",
                        "object": "option"
                    }
                },
                {
                    "id": 10244,
                    "state": {
                        "description": "Change request is is transient state...Processing.",
                        "id": 2,
                        "name": "Processing",
                        "object": "option"
                    }
                },
                {
                    "id": 10251,
                    "state": {
                        "description": "Change request has succeeded.",
                        "id": 3,
                        "name": "Succeeded",
                        "object": "option"
                    },
                    "updatedon": 1231008346317
                }
            ],
            "id": 60531,
            "lastupdatedon": 1231008346317,
            "object": "job",
            "objecttype": {
                "description": null,
                "id": 1,
                "name": "VirtualServer",
                "object": "option"
            },
            "owner": "ankit@gogrid.com"
        },
        {
            "attempts": 1,
            "command": {
                "description": "Create Virtual Server",
                "id": 6,
                "name": "CreateVirtualServer",
                "object": "option"
            },
            "createdon": 1231007606467,
            "currentstate": {
                "description": "Change request has succeeded.",
                "id": 3,
                "name": "Succeeded",
                "object": "option"
            },
            "datacenter": {
                "description": "US West 1 Datacenter",
                "id": 1,
                "name": "US-West-1",
                "object": "option"
            },
            "detail": {
                "description": "tetsss",
                "image": "centos51_64_lamp",
                "ip": "208.113.76.32",
                "name": "test",
                "type": "virtual_server"
            },
            "history": [
                {
                    "id": 10239,
                    "state": {
                        "description": "Change request is created but not queued yet",
                        "id": 7,
                        "name": "Created",
                        "object": "option"
                    }
                },
                {
                    "id": 10240,
                    "state": {
                        "description": "Change request is new to the system.",
                        "id": 1,
                        "name": "Queued",
                        "object": "option"
                    }
                },
                {
                    "id": 10241,
                    "state": {
                        "description": "Change request is is transient state...Processing.",
                        "id": 2,
                        "name": "Processing",
                        "object": "option"
                    }
                },
                {
                    "id": 10246,
                    "state": {
                        "description": "Change request has succeeded.",
                        "id": 3,
                        "name": "Succeeded",
                        "object": "option"
                    },
                    "updatedon": 1231008211834
                }
            ],
            "id": 60530,
            "lastupdatedon": 1231008211834,
            "object": "job",
            "objecttype": {
                "description": null,
                "id": 1,
                "name": "VirtualServer",
                "object": "option"
            },
            "owner": "ankit@gogrid.com"
        }
    ],
    "method": "/grid/job/list",
    "status": "success",
    "summary": {
        "numpages": 1,
        "returned": 7,
        "start": 0,
        "total": 7
    }
}

XML Response

<gogrid>
  <response method="/grid/job/list" status="success">
    <summary total="4" start="0" numpages="4" returned="1"/>
    <list>
      <object name="job">
        <attribute name="id">1165</attribute>
        <attribute name="owner">bryan@gogrid.com</attribute>
        <attribute name="createdon">1247780915810</attribute>
        <attribute name="lastupdatedon"></attribute>
        <attribute name="attempts">1</attribute>
        <attribute name="history">          <list>
            <object name="job_history">
              <attribute name="id">4233</attribute>
              <attribute name="state">
                <object name="option">
                  <attribute name="id">7</attribute>
                  <attribute name="name">Created</attribute>
                  <attribute name="description">Change request is created but not queued yet</attribute>
                </object>
              </attribute>
              <attribute name="note"></attribute>
              <attribute name="updatedon">1247780915818</attribute>
            </object>
            <object name="job_history">
              <attribute name="id">4234</attribute>
              <attribute name="state">
                <object name="option">
                  <attribute name="id">1</attribute>
                  <attribute name="name">Queued</attribute>
                  <attribute name="description">Change request is new to the system.</attribute>
                </object>
              </attribute>
              <attribute name="note"></attribute>
              <attribute name="updatedon">1247780915857</attribute>
            </object>
            <object name="job_history">
              <attribute name="id">4235</attribute>
              <attribute name="state">
                <object name="option">
                  <attribute name="id">2</attribute>
                  <attribute name="name">Processing</attribute>
                  <attribute name="description">Change request is is transient state...Processing.</attribute>
                </object>
              </attribute>
              <attribute name="note"></attribute>
              <attribute name="updatedon">1247780922080</attribute>
            </object>
          </list>        
        </attribute>
        <attribute name="currentstate">
          <object name="option">
            <attribute name="id">2</attribute>
            <attribute name="name">Processing</attribute>
            <attribute name="description">Change request is is transient state...Processing.</attribute>
          </object>
        </attribute>
        <attribute name="command">
          <object name="option">
            <attribute name="id">23</attribute>
            <attribute name="name">AddServerImage</attribute>
            <attribute name="description">Add Server Image</attribute>
          </object>
        </attribute>
        <attribute name="objecttype">
          <object name="option">
            <attribute name="id">7</attribute>
            <attribute name="name">ServerImage</attribute>
            <attribute name="description"></attribute>
          </object>
        </attribute>
        <attribute name="detail">{}</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>
    </list>
  </response>
</gogrid>

CSV Response

# SUCCESS, /grid/job/list, TOTAL, 7, NUMPAGES, 1, START, 0, RETURNED, 7
# id,owner,createdon,lastupdatedon,attempts,currentstate.id,currentstate.name,currentstate.description,command.id,command.name,command.description,objecttype.id,objecttype.name,objecttype.description,detail,history.1.id,history.1.state.id,history.1.state.name,history.1.state.description,history.1.note,history.1.updatedon,history.2.id,history.2.state.id,history.2.state.name,history.2.state.description,history.2.note,history.2.updatedon,history.3.id,history.3.state.id,history.3.state.name,history.3.state.description,history.3.note,history.3.updatedon,history.4.id,history.4.state.id,history.4.state.name,history.4.state.description,history.4.note,history.4.updatedon
60531,ankit@gogrid.com,1231007644632,1231008346317,1,3,Succeeded,Change request has succeeded.,6,CreateVirtualServer,Create Virtual Server,1,VirtualServer,,"{""type"":""virtual_server"",""description"":""tests"",""image"":""w2k3_64_iis_asp_mssql2k5xp"",""name"":""test 2"",""ip"":""208.113.76.34""}",10242,7,Created,Change request is created but not queued yet,,,10243,1,Queued,Change request is new to the system.,,,10244,2,Processing,Change request is is transient state...Processing.,,,10251,3,Succeeded,Change request has succeeded.,,1231008346317,
60530,ankit@gogrid.com,1231007606467,1231008211834,1,3,Succeeded,Change request has succeeded.,6,CreateVirtualServer,Create Virtual Server,1,VirtualServer,,"{""type"":""virtual_server"",""description"":""tetsss"",""image"":""centos51_64_lamp"",""name"":""test"",""ip"":""208.113.76.32""}",10239,7,Created,Change request is created but not queued yet,,,10240,1,Queued,Change request is new to the system.,,,10241,2,Processing,Change request is is transient state...Processing.,,,10246,3,Succeeded,Change request has succeeded.,,1231008211834,
60505,swapna@gogrid.com,1231002617819,1231002620175,1,3,Succeeded,Change request has succeeded.,3,StartVirtualServer,Start 

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 you 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 with 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 exist on the API Server.
500 UnexpectedError These types of errors indicate an internal system problem. Depending on the severity of the error and whether it is blocking your development, report the error to GoGrid support by emailing the response to apisupport@gogrid.com.
Personal tools