GetReviewableHITs

Description

The GetReviewableHITs operation retrieves the HITs that have a status of Reviewable, or HITs that have a status of Reviewing, and that belong to the Requester calling the operation.

You can use this operation to determine which of your HITs have results, then retrieve those results with the GetAssignmentsForHIT operation. Once a HIT's results have been retrieved and the assignments have been approved or rejected (with ApproveAssignment or RejectAssignment), you can call DisposeHIT to remove the HIT from the results of a call to GetReviewableHITs.

GetReviewableHITs can limit the query to HITs of a specified HIT type. Every HIT has a type with a HIT type ID, whether the type was created explicitly with the RegisterHITType operation, or implicitly when the HIT was created with the CreateHIT operation. See CreateHIT for more information.

GetReviewableHITs returns either HITs with a status of Reviewable, or HITs with a status of Reviewing, based on the Status parameter. A reviewable HIT can be given the "reviewing" status, and reverted back to the reviewable status, with the SetHITAsReviewing operation. See SetHITAsReviewing for more information.

Results are sorted and divided into numbered "pages," and a single page of results is returned by the operation. Sorting and pagination can be controlled with parameters to the operation.

When (PageNumber x PageSize) is less than 100, you can get reliable results when you use any of the sort properties. If this number is greater than 100, use the Enumeration sort property for best results. The Enumeration sort property guarantees that all reviewable HITs are returned with no duplicates, but not in any specific order.

Reviewable and Reviewing HITs

A HIT becomes Reviewable when either a number of assignments equal to MaxAssignments have been submitted by Workers, or the HIT's LifetimeInSeconds has elapsed.

As part of your application's HIT processing routine, the application can switch a HIT's status from Reviewable to a status called Reviewing. You can switch a HIT between the two status values using the SetHITAsReviewing. Depending on the Status parameter, the GetReviewableHITs operation returns either HITs with a status of Reviewable, or HITs with a status of Reviewing.

The switchable Reviewable/Reviewing status allows you to control which of your completed HITs are returned by a call to the GetReviewableHITs operation. Your application could use this to manage HIT review with multiple simultaneous processes, or postpone approval for a HIT's assignments until other data is gathered.

Sample Request: Using GetReviewableHITs (REST)

The following example of a call to the GetReviewableHITs operation retrieves five of the Requester's reviewable HITs, using the default sort order (expiration date, ascending).

http://mechanicalturk.amazonaws.com/?Service=AWSMechanicalTurkRequester
&AWSAccessKeyId=[the Requester's Access Key ID]
&Version=2008-04-01
&Operation=GetReviewableHITs
&Signature=[signature for this request]
&Timestamp=[your system's local time]
&PageSize=5
&PageNumber=1

Request Parameters

A request to the Mechanical Turk Service includes parameters that control its behavior and the data it returns. Required parameters must be included for the request to succeed.

GetReviewableHITs accepts parameters common to all operations. Some common parameters are required. See Common Parameters for more information.

The following parameters are specific to the GetReviewableHITs operation:

Name	Description	Type	Value
`Operation`	The operation to call. To access the `GetReviewableHITs` operation, set the `Operation` parameter to `GetReviewableHITs`.	Required	`GetReviewableHITs`
`HITTypeId`	The ID of the HIT type of the HITs to consider for the query. If not specified, all of the Requester's HITs will be considered for the query.	Optional	A valid HIT type ID
`Status`	The status of the HITs to return, either `Reviewable` or `Reviewing`. If not specified, `GetReviewableHITs` will return HITs with a status of `Reviewable`. To specify more than one status for the query (such as to query both `Reviewable` and `Reviewing` HITs), specify multiple `Status` parameters.	Optional	`Reviewable` \| `Reviewing`
`SortProperty`	The field on which to sort the results returned by the operation. If `SortProperty` is not specified, the set of HITs is sorted by `Expiration`.	Optional	`Title` \| `Reward` \| `Expiration` \| `CreationTime` \| `Enumeration`
`SortDirection`	The direction of the sort used with the field specified by `SortProperty`. If `SortDirection` is not specified, the results will be sorted by the field in descending order.	Optional	`Ascending` \| `Descending`
`PageSize`	The number of HITs to include in a "page" of results. The complete sorted result set is divided into pages of this many HITs. `PageSize` must be a number between `1` and `100`. If the `PageSize` parameter is not specified, a default size of `10` elements is used.	Optional	A positive integer
`PageNumber`	The page of results to return. Once the HITs have been filtered, sorted, and divided into pages of size `PageSize`, the page corresponding to `PageNumber` is returned as the results of the operation. If the `PageNumber` parameter is not specified, a default page number of 1 will be used.	Optional	A positive integer

Responses

A successful request for the GetReviewableHITs operation will have a GetReviewableHITsResult element in the response.

The GetReviewableHITsResult element contains the following elements:

Name	Description	Value
`NumResults`	The number of HITs on this page in the filtered results list, equivalent to the number of HITs being returned by this call.	A non-negative integer
`PageNumber`	The number of this page in the filtered results list.	A positive integer
`TotalNumResults`	The total number of HITs in the filtered results list based on this call.	A non-negative integer
`HIT`	The HIT. The response will include one `HIT` element for each HIT returned by the query.	A HIT data structure. For more information on the data structure of a HIT, see the HIT Data Structure.