Jobs API

This API allows M2X users to track the state and progress of asynchronous jobs.

Authentication

All methods described in this page require that a Master API Key is specified in the X-M2X-KEY header. Any attempt to use a Device-level API key would result in a 403 Forbidden response. Learn more about API Keys.

List Jobs

GET /jobs

Retrieve the list of the most recent jobs that belong to the authenticated account. This method accepts the following optional parameters:

  • page Page number to be retrieved. The default value is 1.
  • limit Number of jobs to be returned per page. The default value is 10.
  • state Can be one of queued, working, complete or failed. All returned jobs will be filtered by the given state.
  • device a Device ID; it will list all the jobs that are associated with that specific device. If none is specified, then all jobs belonging to the authenticated account will be returned.

Responses

Success

200 OK
Content-Type: application/json

{
  "jobs": [
    {
      "id": "AUwkV9LFPMlyo_l0P9H0",
      "state": "queued",
      "output": null,
      "errors": null,
      "started": null,
      "finished": null,
      "created": "2015-03-16T20:47:57.627Z",
      "updated": "2015-03-16T20:47:57.627Z"
    },
    {
      "id": "AUwkV9LKPMlyo_l0P9H1",
      "state": "working",
      "output": null,
      "errors": null,
      "started": "2015-03-16T20:49:57.642Z",
      "finished": null,
      "created": "2015-03-16T20:47:57.642Z",
      "updated": "2015-03-16T20:49:57.642Z"
    }
  ],
  "total": 4,
  "pages": 2,
  "limit": 2,
  "current_page": 1
}

View Job Details

GET /jobs/{id}

Responses

Success

200 OK
Content-Type: application/json

{
  "id": "AUwkV9LKPMlyo_l0P9H1",
  "state": "working",
  "output": null,
  "errors": null,
  "started": "2015-03-16T20:49:57.642Z",
  "finished": null,
  "created": "2015-03-16T20:47:57.642Z",
  "updated": "2015-03-16T20:49:57.642Z"
}

Job Not Found

404 Not Found
Content-Type: application/json

{ "message": "Job Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified job does not exist.

View Job Results

GET /jobs/{id}

When a job is completed and its result holds important information, a result field will be included in the View Job Details response. This field will contain information about the processed job. e.g.: The URL of some downloadable result.

200 OK
Content-Type: application/json

{
  "id": "AUwkV9LKPMlyo_l0P9H1",
  "state": "working",
  "output": null,
  "errors": null,
  "started": "2015-03-16T20:49:57.642Z",
  "finished": null,
  "created": "2015-03-16T20:47:57.642Z",
  "updated": "2015-03-16T20:49:57.642Z",
  "result": {
    "url": "http://example.com/"
  }
}