HIT Data Structure

Description

The HIT data structure represents a single HIT, including all the information necessary for a Worker to accept and complete the HIT and claim the reward.

The HIT data structure is used as a response element for the following operations:

HITs and Response Groups

Operations that return a HIT data structure use response groups to determine how much information to return. As described in Common Parameters, the ResponseGroup parameter specifies which sets of elements the service should return, as a set of named groups. For example, the Request response group includes the contents of the operation request in the response.

For the HIT data structure, the Minimal response group returns the HITId. To also return the HIT's Question data, include the HITQuestion response group. To include the other fields in the HIT data structure, specify the HITDetail response group.

The GetHIT operation returns the HITDetail, HITQuestion and Minimal response groups by default.

CreateHIT and DisableHIT can also return additional HIT fields, but their default is Minimal.

Currently, only the Minimal response group is supported for the GetReviewableHITs operation. To retrieve additional HIT data for HITs returned by this operation, use the HIT IDs in the results with GetHIT.

Example: CreateHIT

The following example of the HIT data structure could be returned by a call to the CreateHIT operation. CreateHIT returns an element named HIT, that represents the HIT that was created by the call.

<HIT>
  <HITId>123RVWYBAZW00EXAMPLE</HITId>
  <CreationTime>2005-06-30T23:59:59</CreationTime>
  <HITStatus>Assignable</HITStatus>
  <MaxAssignments>5</MaxAssignments>
  <AutoApprovalDelayInSeconds>86400</AutoApprovalDelayInSeconds>
  <LifetimeInSeconds>86400</LifetimeInSeconds>
  <AssignmentDurationInSeconds>300</AssignmentDurationInSeconds>
  <Reward>
    <Amount>25</Amount>
    <CurrencyCode>USD</CurrencyCode>
    <FormattedPrice>$0.25</FormattedPrice>
  </Reward>
  <Title>Location and Photograph Identification</Title>
  <Description>Select the image that best represents...</Description>
  <Keywords>location, photograph, image, identification, opinion</Keywords>
  <Question>
    &lt;QuestionForm&gt;
      [XML-encoded Question data]
    &lt;/QuestionForm&gt;
  </Question>
  <QualificationRequirement>
    <QualificationTypeId>789RVWYBAZW00EXAMPLE</QualificationTypeId>
    <Comparator>GreaterThan</Comparator>
    <Value>18</Value>
  </QualificationRequirement>
  <HITReviewStatus>NotReviewed</HITReviewStatus>
</HIT>

Elements

The HIT structure may contain the following elements.

Name	Description	Value
HITId	A unique identifier for the HIT. A HIT is given a HIT ID when CreateHIT is called, and it retains that ID forever.	A valid HIT ID
CreationTime	The date and time the HIT was created.	A dateTime in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as `2005-01-31T23:59:59Z`
Title	The title of the HIT.	A string
Description	A general description of the HIT.	A string
Keywords	One or more words or phrases that describe the HIT, separated by commas. Search terms similar to a HIT's keywords are more likely to have the HIT in the search results.	A string
HITStatus	The status of the HIT and its assignments. A HIT with a status of `Assignable` is ready to be found and accepted by Workers. A HIT begins in the `Assignable` status, and remains `Assignable` until MaxAssignments assignments are in progress, or until the HIT's LifetimeInSeconds has elapsed. A HIT with a status of `NotAssignable` is no longer available to be accepted by Workers, and has one or more assignments in progress. A HIT remains `NotAssignable` until all assignments have been submitted, returned or abandoned. A HIT with a status of `Reviewable` has submitted results for MaxAssignments assignments, or the HIT's LifetimeInSeconds has elapsed and all assignments that were in progress have been submitted, returned or abandoned. A Requester can retrieve all HITs with this status using the GetReviewableHITs operation. When a HIT is `Reviewable`, the Requester can retrieve the results, and approve or reject the assignments. A HIT has a status of `Disposed` after DisposeHIT has been called for the HIT. Because a HIT may be removed from the system at any time after being disposed, calling GetHIT for a disposed HIT may return the HIT with this status, or it may return nothing.	`Assignable` \| `NotAssignable` \| `Reviewable` \| `Disposed`
Reward	The amount of money the Requester will pay a user for successfully completing the HIT. The value is a Price data structure. For more information, see the Price Data Structure.	A Price data structure
LifetimeInSeconds	An amount of time after which the HIT will no longer be available for users to accept. The HIT becomes unavailable even if the requested number of assignments, specified by MaxAssignments, has not yet been fulfilled. The initial LifetimeInSeconds value is specified as a parameter to CreateHIT. When the HIT is created, the HIT's life begins, and this value begins counting down. When the HIT data is returned by the service, such as from a call to GetHIT, the LifetimeInSeconds value represents how much time remains until the HIT expires from the time the operation call is complete.	A number of seconds, as a positive integer
AssignmentDurationInSeconds	The length of time a user has to complete the HIT after accepting it. If a user does not complete the assignment in the specified duration, the assignment is considered abandoned. If the HIT is still active (it has not expired), the assignment becomes available for other users to find and accept.	A number of seconds, as a positive integer
MaxAssignments	The number of times the HIT can be accepted and completed before the HIT becomes unavailable. Each Worker can complete a HIT only once, so multiple assignments are guaranteed to be completed by multiple Workers. If not specified, the value is 1.	A positive integer
AutoApprovalDelayInSeconds	An amount of time after an assignment for the HIT has been submitted by the Worker after which the results ought to automatically be considered "approved" by the Requester.	A number of seconds, as a positive integer
QualificationRequirement	A condition that a Worker's Qualifications must meet before the Worker is allowed to accept the HIT. The condition specifies that the Worker must have a Qualification of a particular Qualification type, and that its value must compare to the requirement's value in the specified way: equal to, not equal to, less than, less than or equal to, greater than or equal to, or greater than. A HIT may have between zero and ten Qualification requirements. All requirements must be met by a Worker's Qualifications for the Worker to accept the HIT. The value of this element is a Qualification requirement data structure. For more information, see the QualificationRequirement Data Structure.	A Qualification requirement data structure
Question	The data the Worker completing the HIT will use to produce the results. This value is an XML data structure. See the QuestionForm data structure for more information.	XML data for the question, a QuestionForm data structure
RequesterAnnotation	An arbitrary data field for use by the Requester that created the HIT. This field is only visible to the creator of the HIT.	A string
NumberOfSimilarHITs	The number of HITs whose fields are identical to this HIT, other than the Question field. See the documentation for the CreateHIT operation for a description of HIT similarity.	A non-negative integer
HITReviewStatus	If a HIT is submitted that violates Mechanical Turk's policies for appropriate content, a Mechanical Turk user can request that a HIT be reviewed by an administrator. HITReviewStatus indicates whether the HIT has not been reviewed, has been marked for review by a user, or has been reviewed by an administrator and deemed appropriate or inappropriate.	`NotReviewed` \| `MarkedForReview` \| `ReviewedAppropriate` \| `ReviewedInappropriate`

Name

Description

Value

HITId

A unique identifier for the HIT. A HIT is given a HIT ID when CreateHIT is called, and it retains that ID forever.

A valid HIT ID

CreationTime

The date and time the HIT was created.

A dateTime in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as 2005-01-31T23:59:59Z

Title

The title of the HIT.

A string

Description

A general description of the HIT.

A string

Keywords

One or more words or phrases that describe the HIT, separated by commas. Search terms similar to a HIT's keywords are more likely to have the HIT in the search results.

A string

HITStatus

The status of the HIT and its assignments.

A HIT with a status of Assignable is ready to be found and accepted by Workers. A HIT begins in the Assignable status, and remains Assignable until MaxAssignments assignments are in progress, or until the HIT's LifetimeInSeconds has elapsed.

A HIT with a status of NotAssignable is no longer available to be accepted by Workers, and has one or more assignments in progress. A HIT remains NotAssignable until all assignments have been submitted, returned or abandoned.

A HIT with a status of Reviewable has submitted results for MaxAssignments assignments, or the HIT's LifetimeInSeconds has elapsed and all assignments that were in progress have been submitted, returned or abandoned. A Requester can retrieve all HITs with this status using the GetReviewableHITs operation. When a HIT is Reviewable, the Requester can retrieve the results, and approve or reject the assignments.

A HIT has a status of Disposed after DisposeHIT has been called for the HIT. Because a HIT may be removed from the system at any time after being disposed, calling GetHIT for a disposed HIT may return the HIT with this status, or it may return nothing.

Assignable | NotAssignable | Reviewable | Disposed

Reward

The amount of money the Requester will pay a user for successfully completing the HIT.

The value is a Price data structure. For more information, see the Price Data Structure.

A Price data structure

LifetimeInSeconds

An amount of time after which the HIT will no longer be available for users to accept. The HIT becomes unavailable even if the requested number of assignments, specified by MaxAssignments, has not yet been fulfilled.

The initial LifetimeInSeconds value is specified as a parameter to CreateHIT. When the HIT is created, the HIT's life begins, and this value begins counting down. When the HIT data is returned by the service, such as from a call to GetHIT, the LifetimeInSeconds value represents how much time remains until the HIT expires from the time the operation call is complete.

A number of seconds, as a positive integer

AssignmentDurationInSeconds

The length of time a user has to complete the HIT after accepting it.

If a user does not complete the assignment in the specified duration, the assignment is considered abandoned. If the HIT is still active (it has not expired), the assignment becomes available for other users to find and accept.

A number of seconds, as a positive integer

MaxAssignments

The number of times the HIT can be accepted and completed before the HIT becomes unavailable. Each Worker can complete a HIT only once, so multiple assignments are guaranteed to be completed by multiple Workers.

If not specified, the value is 1.

A positive integer

AutoApprovalDelayInSeconds

An amount of time after an assignment for the HIT has been submitted by the Worker after which the results ought to automatically be considered "approved" by the Requester.

A number of seconds, as a positive integer

QualificationRequirement

A condition that a Worker's Qualifications must meet before the Worker is allowed to accept the HIT.

The condition specifies that the Worker must have a Qualification of a particular Qualification type, and that its value must compare to the requirement's value in the specified way: equal to, not equal to, less than, less than or equal to, greater than or equal to, or greater than.

A HIT may have between zero and ten Qualification requirements. All requirements must be met by a Worker's Qualifications for the Worker to accept the HIT.

The value of this element is a Qualification requirement data structure. For more information, see the QualificationRequirement Data Structure.

A Qualification requirement data structure

Question

The data the Worker completing the HIT will use to produce the results. This value is an XML data structure. See the QuestionForm data structure for more information.

XML data for the question, a QuestionForm data structure

RequesterAnnotation

An arbitrary data field for use by the Requester that created the HIT. This field is only visible to the creator of the HIT.

A string

NumberOfSimilarHITs

The number of HITs whose fields are identical to this HIT, other than the Question field. See the documentation for the CreateHIT operation for a description of HIT similarity.

A non-negative integer

HITReviewStatus

If a HIT is submitted that violates Mechanical Turk's policies for appropriate content, a Mechanical Turk user can request that a HIT be reviewed by an administrator. HITReviewStatus indicates whether the HIT has not been reviewed, has been marked for review by a user, or has been reviewed by an administrator and deemed appropriate or inappropriate.

NotReviewed | MarkedForReview | ReviewedAppropriate | ReviewedInappropriate