The GetAssignmentsForHIT operation retrieves completed assignments for a HIT. You can use this operation to retrieve the results for a HIT.
You can only get assignments for a HIT in the "Reviewable" status, such as for HITs returned by GetReviewableHITs. GetAssignmentsForHIT will not return any data for a HIT until all assignments have been submitted, or the HIT has expired and outstanding assignments have passed their deadlines.
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.
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.
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/onca/xml?Service=AWSMechanicalTurkRequester &AWSAccessKeyId=[the Requester's Access Key ID] &Operation=GetAssignmentsForHIT &Signature=[signature for this request] &Timestamp=[your system's local time] &HITId=123RVWYBAZW00EXAMPLE &PageSize=5 &PageNumber=1
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 |
| 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 | Answer | 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 |
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. |