Amazon Glacier
Developer Guide (API Version 2012-06-01)
AWS Documentation » Amazon Glacier » Developer Guide » API Reference for Amazon Glacier » Job Operations » List Jobs (GET jobs)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

List Jobs (GET jobs)

Description

This operation lists jobs for a vault including jobs that are in-progress and jobs that have recently finished.

Note

Amazon Glacier retains recently completed jobs for a period before deleting them; however, it eventually removes completed jobs. The output of completed jobs can be retrieved. Retaining completed jobs for a period of time after they have completed enables you to get a job output in the event you miss the job completion notification or your first attempt to download it fails. For example, suppose you start an archive retrieval job to download an archive. After the job completes, you start to download the archive but encounter a network error. In this scenario, you can retry and download the archive while the job exists.

To retrieve an archive or retrieve a vault inventory from Amazon Glacier, you first initiate a job, and after the job completes, you download the data. For an archive retrieval, the output is the archive data, and for an inventory retrieval, it is the inventory list. The List Job operation returns a list of these jobs sorted by job initiation time.

The List Jobs operation supports pagination. By default, this operation returns up to 1,000 jobs in the response. You should always check the response marker field for a marker at which to continue the list; if there are no more items the marker field is null. To return a list of jobs that begins at a specific job, set the marker request parameter to the value you obtained from a previous List Jobs request. You can also limit the number of jobs returned in the response by specifying the limit parameter in the request.

Additionally, you can filter the jobs list returned by specifying an optional statuscode (InProgress, Succeeded, or Failed) and completed (true, false) parameter. The statuscode allows you to specify that only jobs that match a specified status are returned. The completed parameter allows you to specify that only jobs in specific completion state are returned.

Requests

Syntax

To returns a list of jobs of all types, send a GET request to the URI of the vault's jobs subresource.

GET /AccountId/vaults/VaultName/jobs HTTP/1.1
Host: glacier.Region.amazonaws.com
Date: Date
Authorization: SignatureValue
x-amz-glacier-version: 2012-06-01

Note

The AccountId is the AWS Account ID. This value must match the AWS Account ID associated with the credentials used to sign the request. You can either specify AWS Account ID or optionally a '-' in which case Amazon Glacier uses the AWS Account ID associated with the credentials used to sign the request. If you specify your Account ID, do not include dashes in it.

Request Parameters

Name Description Required
completed

Specifies the state of the jobs to return. You can specify true or false.

Type: Boolean

Constraints: None

 No
limit

Specifies that the response be limited to the specified number of items or fewer. If not specified, the List Jobs operation returns up to 1000 jobs.

Type: Number

Constraints: Minimum value of 1. Maximum value of 1000.

 No
marker

An opaque string used for pagination. marker specifies the job at which the listing of jobs should begin. Get the marker value from a previous List Jobs response. You need only include the marker if you are continuing the pagination of results started in a previous List Jobs request.

Type: String

Constraints: None

 No
statuscode

Specifies the type of job status to return.

Type: String

Constraints: One of the values InProgress, Succeeded, or Failed.

 No

Request Headers

This operation uses only response headers that are common to most responses. For information about common response headers, see Common Response Headers.

Request Body

This operation does not have a request body.

Responses

Syntax

HTTP/1.1 200 OK
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Location: Location 
Content-Type: application/json
Content-Length: Length

{
  "JobList": [
    {     
      "Action": String,
      "ArchiveId": String,
      "ArchiveSizeInBytes": Number,
      "ArchiveSHA256TreeHash": String,
      "Completed": Boolean,
      "CompletionDate": String,
      "CreationDate": String,
      "InventorySizeInBytes": String,
      "JobDescription": String,
      "JobId": String,
      "RetrievalByteRange": String,
      "SHA256TreeHash": String,
      "SNSTopic": String,
      "StatusCode": String,
      "StatusMessage": String,
      "VaultARN": String
    },
  ...
  ],
  "Marker": String
}

Response Headers

This operation uses only response headers that are common to most responses. For information about common response headers, see Common Response Headers.

Response Body

The response body contains the following JSON fields.

Action

For archive retrieval jobs, this value is ArchiveRetrieval. For inventory retrieval jobs, this value is InventoryRetrieval.

Type: String

ArchiveId

The ID of the archive that was requested in an archive retrieval. This field only appears for archive retrieval job descriptions.

Type: String

ArchiveSizeInBytes

The size of the archive for which the archive retrieval job request was initiated.

Type: Number

ArchiveSHA256TreeHash

The SHA256 tree hash of the entire archive for an archive retrieval. For inventory retrieval jobs, this field is null.

Type: String

Completed

true if the job is completed; false otherwise.

Type: Boolean

CompletionDate

The UTC time the job completed.

Type: A string representation of ISO 8601 date format, for example, 2012-03-20T17:03:43.221Z.

CreationDate

The UTC time the job started.

Type: A string representation of ISO 8601 date format, for example, 2012-03-20T17:03:43.221Z.

InventorySizeInBytes

The size of the inventory associated with an inventory retrieval job request. This field appears only for inventory retrieval job descriptions.

Type: Number

JobDescription

A description of the job.

Type: String

JobId

The ID that represents the job in Amazon Glacier.

Type: String

JobList

An array of job objects. Each job object contains a set of name-value pairs describing the job.

Type: Array

Marker

An opaque string that represents where to continue pagination of the results. You use the marker in a new List Jobs request to obtain more jobs in the list. If there are no more jobs, this value is null.

Type: String

RetrievalByteRange

The retrieved byte range for archive retrieval jobs in the form "StartByteValue-EndByteValue" If no range was specified in the archive retrieval, then the whole archive is retrieved and StartByteValue equals 0 and EndByteValue equals the size of the archive minus 1. For inventory retrieval jobs this field is null.

Type: String

SHA256TreeHash

The SHA256 tree hash value for the requested range of an archive. If the Initiate a Job (POST jobs) request for an archive specified a tree-hash aligned range, then this field returns a value. For more information about tree hash aligned ranges for archive range retrievals, see Receiving Checksums When Downloading Data.

For the specific case when the whole archive is retrieved, this value is the same as the ArchiveSHA256TreeHash value.

This field is null in the following situations:

  • Archive retrieval jobs that specify a range that is not tree-hash aligned.

  • Archival jobs that specify a range that is not equal to the whole archive and the job status is InProgress. After the job completes, the SHA256TreeHash field will have a value.

  • Inventory jobs.

Type: String

SNSTopic

The Amazon Resource Name (ARN) that represents an Amazon SNS topic where notification of job completion or failure is sent, if notification was configured in the job initiation (Initiate a Job (POST jobs)).

Type: String

StatusCode

The job status code. The values can be Succeeded, Failed, or InProgress.

Type: String

StatusMessage

The job status message.

Type: String

VaultARN

The Amazon Resource Name (ARN) of the vault of which the job is a subresource.

Type: String

Errors

For information about Amazon Glacier exceptions and error messages, see Error Responses.

Examples

The following examples demonstrate how to use return information about vault jobs. The first example returns up to 1,000 jobs, and the second example returns a subset of jobs.

Example - Return All Jobs

Example Request

The following GET request returns up to 1,000 jobs for a vault. 

GET /-/vaults/examplevault/jobs  HTTP/1.1
Host: glacier.us-east-1.amazonaws.com
x-amz-Date: 20120325T120000Z
x-amz-glacier-version: 2012-06-01
Authorization: AWS4-HMAC-SHA256 Credential=/20120525/us-east-1/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2

Example Response

The following response includes an archive retrieval job and an inventory retrieval job.

HTTP/1.1 200 OK
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Sun, 25 Mar 2012 12:00:00 GMT 
Content-Type: application/json
Content-Length: 1444

{
  "JobList": [
    {
      "Action": "ArchiveRetrieval",
      "ArchiveId": "BDfaUQul0dVzYwAMr8YSa_6_8abbhZq-i1oT69g8ByClfJyBgAGBkWl2QbF5os851P7Y7KdZDOHWJIn4rh1ZHaOYD3MgFhK_g0oDPesW34uHQoVGwoIqubf6BgUEfQm_wrU4Jlm3cA",
      "ArchiveSizeInBytes": 1048576,
      "ArchiveSHA256TreeHash": "25499381569ab2f85e1fd0eb93c5406a178ab77c5933056eb5d6e7d4adda609b",
      "Completed": true,
      "CompletionDate": "2012-05-01T00:00:09.304Z",
      "CreationDate": "2012-05-01T00:00:06.663Z",
      "InventorySizeInBytes": null,
      "JobDescription": null,
      "JobId": "hDe9t9DTHXqFw8sBGpLQQOmIM0-JrGtu1O_YFKLnzQ64548qJc667BRWTwBLZC76Ygy1jHYruqXkdcAhRsh0hYv4eVRU",
      "RetrievalByteRange": "0-1048575",
      "SHA256TreeHash": "25499381569ab2f85e1fd0eb93c5406a178ab77c5933056eb5d6e7d4adda609b",
      "SNSTopic": null,
      "StatusCode": "Succeeded",
      "StatusMessage": "Succeeded",
      "VaultARN": "arn:aws:glacier:us-east-1:012345678901:vaults/examplevault"
    },
    {
      "Action": "InventoryRetrieval",
      "ArchiveId": null,
      "ArchiveSizeInBytes": null,
      "ArchiveSHA256TreeHash": null,
      "Completed": true,
      "CompletionDate": "2012-05-11T00:25:18.831Z",
      "CreationDate": "2012-05-11T00:25:14.981Z",
      "InventorySizeInBytes": 1988,
      "JobDescription": null,
      "JobId": "2cvVOnBL36btzyP3pobwIceiaJebM1bx9vZOOUtmNAr0KaVZ4WkWgVjiPldJ73VU7imlm0pnZriBVBebnqaAcirZq_C5",
      "RetrievalByteRange": null,
      "SHA256TreeHash": null,
      "SNSTopic": null,
      "StatusCode": "Succeeded",
      "StatusMessage": "Succeeded",
      "VaultARN": "arn:aws:glacier:us-east-1:012345678901:vaults/examplevault"
    }
  ],
  "Marker": null  
}

Example - Return a Partial List of Jobs

Example Request

The following GET request returns the job specified by the marker parameter. Setting the limit parameter as 2 specifies that up to two jobs are returned.

GET /-/vaults/examplevault/jobs?marker=HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID&limit=1  HTTP/1.1
Host: glacier.us-east-1.amazonaws.com
x-amz-Date: 20120325T120000Z
x-amz-glacier-version: 2012-06-01
Authorization: AWS4-HMAC-SHA256 Credential=/20120525/us-east-1/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2

Example Response

The following response shows one job returned and the marker field returns the next job in the list.

HTTP/1.1 200 OK
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Sun, 25 Mar 2012 12:00:00 GMT 
Content-Type: application/json
Content-Length: 1744

{
  "JobList": [
    {
      "Action": "ArchiveRetrieval",
      "ArchiveId": "58-3KpZfcMPUznvMZNPaKyJx9wODCsWTnqcjtx2CjKZ6b-XgxEuA8yvZOYTPQfd7gWR4GRm2XR08gcnWbLV4VPV_kDWtZJKi0TFhKKVPzwrZnA4-FXuIBfViYUIVveeiBE51FO4bvg",
      "ArchiveSizeInBytes": 8388608,
      "ArchiveSHA256TreeHash": "106086b256ddf0fedf3d9e72f461d5983a2566247ebe7e1949246bc61359b4f4",
      "Completed": true,
      "CompletionDate": "2012-05-01T00:25:20.043Z",
      "CreationDate": "2012-05-01T00:25:16.344Z",
      "InventorySizeInBytes": null,
      "JobDescription": "aaabbbccc",
      "JobId": "s4MvaNHIh6mOa1f8iY4ioG2921SDPihXxh3Kv0FBX-JbNPctpRvE4c2_BifuhdGLqEhGBNGeB6Ub-JMunR9JoVa8y1hQ",
      "RetrievalByteRange": "0-8388607",
      "SHA256TreeHash": "106086b256ddf0fedf3d9e72f461d5983a2566247ebe7e1949246bc61359b4f4",
      "SNSTopic": null,
      "StatusCode": "Succeeded",
      "StatusMessage": "Succeeded",
      "VaultARN": "arn:aws:glacier:us-east-1:012345678901:vaults/examplevault"
    },
    {
      "Action": "ArchiveRetrieval",
      "ArchiveId": "2NVGpf83U6qB9M2u-Ihh61yoFLRDEoh7YLZWKBn80A2i1xG8uieBwGjAr4RkzOHA0E07ZjtI267R03Z-6Hxd8pyGQkBdciCSH1-Lw63Kx9qKpZbPCdU0uTW_WAdwF6lR6w8iSyKdvw",
      "ArchiveSizeInBytes": 1048576,
      "ArchiveSHA256TreeHash": "3d2ae052b2978727e0c51c0a5e32961c6a56650d1f2e4ceccab6472a5ed4a0",
      "Completed": true,
      "CompletionDate": "2012-05-01T16:59:48.444Z",
      "CreationDate": "2012-05-01T16:59:42.977Z",
      "InventorySizeInBytes": null,
      "JobDescription": "aaabbbccc",
      "JobId": "CQ_tf6fOR4jrJCL61Mfk6VM03oY8lmnWK93KK4gLig1UPAbZiN3UV4G_5nq4AfmJHQ_dOMLOX5k8ItFv0wCPN0oaz5dG",
      "RetrievalByteRange": "0-1048575",
      "SHA256TreeHash": "3d2ae052b2978727e0c51c0a5e32961c6a56650d1f2e4ceccab6472a5ed4a0",
      "SNSTopic": null,
      "StatusCode": "Succeeded",
      "StatusMessage": "Succeeded",
      "VaultARN": "arn:aws:glacier:us-east-1:012345678901:vaults/examplevault"
    }
  ],
  "Marker": "CQ_tf6fOR4jrJCL61Mfk6VM03oY8lmnWK93KK4gLig1UPAbZiN3UV4G_5nq4AfmJHQ_dOMLOX5k8ItFv0wCPN0oaz5dG"
}

Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...