GetAssignmentsForHIT

Description

The GetAssignmentsForHIT operation retrieves completed assignments for a HIT. You can use this operation to retrieve the results for a HIT.

You can get assignments for a HIT at any time, even if the HIT is not yet "reviewable". If a HIT requested multiple assignments, and has received some results but has not yet become "reviewable", you can still retrieve the partial results with GetAssignmentsForHIT.

Once you have retrieved the results, you can call ApproveAssignment to initiate payment to the Worker for an assignment. You can call RejectAssignment if you have evaluated the results and determined that they inadequately answer the questions asked by the HIT.

GetAssignmentsForHIT can return submitted assignments awaiting approval, or it can return assignments that have already been approved or rejected. The AssignmentStatus parameter controls which set of assignments for a HIT are returned.

Only the Requester who created the HIT can retrieve its assignments.

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.

Sample Request: Using GetAssignmentsForHIT (REST)

The following example of a call to the GetAssignmentsForHIT operation retrieves five assignments for a HIT, using the default sort order (SubmitTime, ascending).

http://mechanicalturk.amazonaws.com/xml?Service=AWSMechanicalTurkRequester
&AWSAccessKeyId=[the Requester's Access Key ID]
&Version=2008-04-01
&Operation=GetAssignmentsForHIT
&Signature=[signature for this request]
&Timestamp=[your system's local time]
&HITId=123RVWYBAZW00EXAMPLE
&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.

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

The following parameters are specific to the GetAssignmentsForHIT operation:

Name	Description	Type	Value
`Operation`	The operation you would like to call. To access the `GetAssignmentsForHIT` operation, set the `Operation` parameter to `GetAssignmentsForHIT`.	Required	`GetAssignmentsForHIT`
`HITId`	The ID of the HIT whose completed assignments are to be returned.	Required	A valid HIT ID
`AssignmentStatus`	The status of the assignments to return. If not specified, all assignments that have been submitted, including those that have been approved or rejected, will be returned.	Optional	`Submitted` \| `Approved` \| `Rejected`
`SortProperty`	The field on which to sort the results returned by the operation. If `SortProperty` is not specified, the set of assignments is sorted by `SubmitTime`.	Optional	`AcceptTime` \| `SubmitTime` \| `AssignmentStatus`
`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 ascending order.	Optional	`Ascending` \| `Descending`
`PageSize`	The number of assignments to include in a "page" of results. The complete sorted result set is divided into pages of this many assignments. `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 assignments 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 GetAssignmentsForHIT operation will have a GetAssignmentsForHITResult element in the response.

The GetAssignmentsForHITResult element contains the following elements:

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