Get Batch Job's Status and Results

Once a batch job is queued you can check on its status with this API. If the job is complete and results are available, they will be included in the response body.

Important: Complete batch jobs are retained for up to three days, after which they are purged automatically and no longer available.

API Request

API Endpoints

HTTP Verbs and URIs

GET /v2/jobs/{jobId}
  • Get the status of a job by ID.

Parameters

Parameter Description Valid Values
{jobId} The ID of the job that was returned when you created it. Integer ID as supplied by aWhere

Query String Parameters

No query string parameters are supported.

Request Body

None

HTTP Headers

Remember to always send your OAuth2 Access Token in the Authorization header (see Authentication). This API doesn't require any additional headers.

API Response

Response HTTP Status Codes and Headers

This API returns standard HTTP status codes and headers for aWhere APIs. No additional headers are returned.

Response Body

Format for Incomplete, Cancelled, or Purged Jobs

{
 "jobStatus":"{jobStatus}",
 "jobId":{jobId},
 "title":"{jobTitle}",
 "type":"{jobType}",
 "dateRequested":"{dateRequested}",
 "queuePosition":{queuePosition}
}

Format for Complete Jobs

{
 "jobStatus":"{jobStatus}",
 "jobId":{jobId},
 "title":"{jobTitle}",
 "type":"{jobType}",
 "dateRequested":"{dateRequested}",
 "results":[{
    "title":"{requestTitle}",
    "api":"{verb} {endpoint}",
    "httpStatus":"{statusCode}",
    "payload":{payloadObject}
    },{
    ...
    }]
}

Property Descriptions

Name Description
{jobStatus} The current status of the job. The options are: queued, queued but may also be running,done, cancelled, or purged.
{jobId} The Job ID. You will need this to retrieve the job status and results.
{jobTitle} The title you gave for the entire job.
{jobType} The type of job, which current is only ever batch.
{dateRequested} The timestamp of when the job was created.
{queuePosition} If the job is queued, this is its position in the queue. Otherwise this property will not be included in the response.
Members of the results Array
{requestTitle} The title of each individual request, if one was supplied.
{verb} {endpoint} The Verb+URI that you asked the Batch Jobs system to retrieve.
{statusCode} The HTTP Status code for the request. This uses standard HTTP codes, so 200 means the request was successful, whereas 400 or 404 means there was a mistake in the request. If one request fails it does not impact the rest of the batch.
{payloadObject} The complete payload that would be returned by the API if it were being called individually.

Example

Request

Endpoint

GET /v2/jobs/24023

Response

Body

This example shows the completed job from the example on the Create a Job API reference.

{"jobStatus":"done",
 "jobId":24023,
 "title":"Yesterdays Weather, All Fields",
 "type":"batch",
 "dateRequested":"2015-07-02T10:00:00Z",
 "results":[{
    "title":"Field 1 Yesterday",
    "api":"GET /v2/weather/fields/1/observations/2015-07-01?properties=temperatures,precipitation",
    "httpStatus":"200",
    "payload":{
        "date":"2015-07-01",
        "location":":{
            "latitude":37.796374,
            "longitude":-96.5246872,
            "fieldId":"1",
        },
        "temperatures":{ 
            "max":90,
            "min":72, 
            "units":"F"
            },
        "precipitation":{
            "amount":0.2,
            "units":"in"
            },
        "_links":{ 
            "self":{"href":"/v2/weather/fields/1/observations/2015-07-01?properties=temperatures,precipitation"},
            "curies":[{
                "name":"awhere",
                "href":"http://awhere.com/rels/{rel}",
                "templated":true
                }],
            "awhere:field":{"href":"/v2/fields/1"}
            }
        }
    },{
    "title":"Field 2 Yesterday",
    "api":"GET /v2/weather/fields/2/observations/2015-07-01?properties=temperatures,precipitation",
    "httpStatus":"200",
    "payload":{
        "date":"2015-07-01",
        "location":":{
            "latitude":38.6250692,
            "longitude":-97.1728805,
            "fieldId":"1",
        },
        "temperatures":{ 
            "max":88,
            "min":73, 
            "units":"F"
            },
        "precipitation":{
            "amount":0.5,
            "units":"in"
            },
        "_links":{ 
            "self":{"href":"/v2/weather/fields/2/observations/2015-07-01?properties=temperatures,precipitation"},
            "curies":[{
                "name":"awhere",
                "href":"http://awhere.com/rels/{rel}",
                "templated":true
                }],
            "awhere:field":{"href":"/v2/fields/2"}
            }
        }
    },{
    "title":"Field 3 Yesterday",
    "api":"GET /v2/weather/fields/3/observations/2015-07-01?properties=temperatures,precipitation",
    "httpStatus":"200",
    "payload":{
        "date":"2015-07-01",
        "location":":{
            "latitude":37.4281319,
            "longitude":-95.234111,
            "fieldId":"1",
        },
        "temperatures":{ 
            "max":86,
            "min":70, 
            "units":"F"
            },
        "precipitation":{
            "amount":1.25,
            "units":"in"
            },
        "_links":{ 
            "self":{"href":"/v2/weather/fields/3/observations/2015-07-01?properties=temperatures,precipitation"},
            "curies":[{
                "name":"awhere",
                "href":"http://awhere.com/rels/{rel}",
                "templated":true
                }],
            "awhere:field":{"href":"/v2/fields/3"}
            }
        }
    },{
    "title":"Field 4 Yesterday",
    "api":"GET /v2/weather/fields/4/observations/2015-07-01?properties=temperatures,precipitation",
    "httpStatus":"200",
    "payload":{
        "date":"2015-07-01",
        "location":":{
            "latitude":38.939199,
            "longitude":-99.010101,
            "fieldId":"1",
        },
        "temperatures":{ 
            "max":95,
            "min":80, 
            "units":"F"
            },
        "precipitation":{
            "amount":0,
            "units":"in"
            },
        "_links":{ 
            "self":{"href":"/v2/weather/fields/4/observations/2015-07-01?properties=temperatures,precipitation"},
            "curies":[{
                "name":"awhere",
                "href":"http://awhere.com/rels/{rel}",
                "templated":true
                }],
            "awhere:field":{"href":"/v2/fields/4"}
            }
        }
    },{
    "title":"Field 5 Yesterday",
    "api":"GET /v2/weather/fields/5/observations/2015-07-01?properties=temperatures,precipitation",
    "httpStatus":"200",
    "payload":{
        "date":"2015-07-01",
        "location":":{
            "latitude":35.111334,
            "longitude":-95.130031,
            "fieldId":"1",
        },
        "temperatures":{ 
            "max":101,
            "min":78, 
            "units":"F"
            },
        "precipitation":{
            "amount":0,
            "units":"in"
            },
        "_links":{ 
            "self":{"href":"/v2/weather/fields/5/observations/2015-07-01?properties=temperatures,precipitation"},
            "curies":[{
                "name":"awhere",
                "href":"http://awhere.com/rels/{rel}",
                "templated":true
                }],
            "awhere:field":{"href":"/v2/fields/5"}
            }
        }
    }]
}