You are viewing the documentation for an older version of boto (boto2).

Boto3, the next version of Boto, is now stable and recommended for general use. It can be used side-by-side with Boto in the same project, so it is easy to start using Boto3 in your existing projects as well as new projects. Going forward, API updates and all new feature work will be focused on Boto3.

For more information, see the documentation for boto3.




class boto.mturk.connection.Assignment(connection)

Class to extract an Assignment structure from a response (used in ResultSet)

Will have attributes named as per the Developer Guide, e.g. AssignmentId, WorkerId, HITId, Answer, etc

endElement(name, value, connection)
class boto.mturk.connection.BaseAutoResultElement(connection)

Base class to automatically add attributes when parsing XML

endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.mturk.connection.FileUploadURL(connection)

Class to extract an FileUploadURL structure from a response

class boto.mturk.connection.HIT(connection)

Class to extract a HIT structure from a response (used in ResultSet)

Will have attributes named as per the Developer Guide, e.g. HITId, HITTypeId, CreationTime


Has this HIT expired yet?

class boto.mturk.connection.HITTypeId(connection)

Class to extract an HITTypeId structure from a response

class boto.mturk.connection.MTurkConnection(aws_access_key_id=None, aws_secret_access_key=None, is_secure=True, port=None, proxy=None, proxy_port=None, proxy_user=None, proxy_pass=None, host=None, debug=0, https_connection_factory=None, security_token=None, profile_name=None)
APIVersion = '2014-08-15'
approve_assignment(assignment_id, feedback=None)
approve_rejected_assignment(assignment_id, feedback=None)
assign_qualification(qualification_type_id, worker_id, value=1, send_notification=True)
block_worker(worker_id, reason)

Block a worker from working on my tasks.

change_hit_type_of_hit(hit_id, hit_type)

Change the HIT type of an existing HIT. Note that the reward associated with the new HIT type must match the reward of the current HIT type in order for the operation to be valid.

create_hit(hit_type=None, question=None, hit_layout=None, lifetime=datetime.timedelta(7), max_assignments=1, title=None, description=None, keywords=None, reward=None, duration=datetime.timedelta(7), approval_delay=None, annotation=None, questions=None, qualifications=None, layout_params=None, response_groups=None)

Creates a new HIT. Returns a ResultSet See:

create_qualification_type(name, description, status, keywords=None, retry_delay=None, test=None, answer_key=None, answer_key_xml=None, test_duration=None, auto_granted=False, auto_granted_value=1)

Create a new Qualification Type.

name: This will be visible to workers and must be unique for a
given requester.

description: description shown to workers. Max 2000 characters.

status: ‘Active’ or ‘Inactive’

keywords: list of keyword strings or comma separated string.
Max length of 1000 characters when concatenated with commas.
retry_delay: number of seconds after requesting a
qualification the worker must wait before they can ask again. If not specified, workers can only request this qualification once.

test: a QuestionForm

answer_key: an XML string of your answer key, for automatically
scored qualification tests. (Consider implementing an AnswerKey class for this to support.)

test_duration: the number of seconds a worker has to complete the test.

auto_granted: if True, requests for the Qualification are granted
immediately. Can’t coexist with a test.

auto_granted_value: auto_granted qualifications are given this value.

disable_hit(hit_id, response_groups=None)

Remove a HIT from the Mechanical Turk marketplace, approves all submitted assignments that have not already been approved or rejected, and disposes of the HIT and all assignment data.

Assignments for the HIT that have already been submitted, but not yet approved or rejected, will be automatically approved. Assignments in progress at the time of the call to DisableHIT will be approved once the assignments are submitted. You will be charged for approval of these assignments. DisableHIT completely disposes of the HIT and all submitted assignment data. Assignment results data cannot be retrieved for a HIT that has been disposed.

It is not possible to re-enable a HIT once it has been disabled. To make the work from a disabled HIT available again, create a new HIT.


Dispose of a HIT that is no longer needed.

Only HITs in the “reviewable” state, with all submitted assignments approved or rejected, can be disposed. A Requester can call GetReviewableHITs to determine which HITs are reviewable, then call GetAssignmentsForHIT to retrieve the assignments. Disposing of a HIT removes the HIT from the results of a call to GetReviewableHITs.


TODO: Document.

static duration_as_seconds(duration)

Expire a HIT that is no longer needed.

The effect is identical to the HIT expiring on its own. The HIT no longer appears on the Mechanical Turk web site, and no new Workers are allowed to accept the HIT. Workers who have accepted the HIT prior to expiration are allowed to complete it or return it, or allow the assignment duration to elapse (abandon the HIT). Once all remaining assignments have been submitted, the expired HIT becomes”reviewable”, and will be returned by a call to GetReviewableHITs.

extend_hit(hit_id, assignments_increment=None, expiration_increment=None)

Increase the maximum number of assignments, or extend the expiration date, of an existing HIT.

NOTE: If a HIT has a status of Reviewable and the HIT is extended to make it Available, the HIT will not be returned by GetReviewableHITs, and its submitted assignments will not be returned by GetAssignmentsForHIT, until the HIT is Reviewable again. Assignment auto-approval will still happen on its original schedule, even if the HIT has been extended. Be sure to retrieve and approve (or reject) submitted assignments before extending the HIT, if so desired.


Return all of a Requester’s HITs

Despite what search_hits says, it does not return all hits, but instead returns a page of hits. This method will pull the hits from the server 100 at a time, but will yield the results iteratively, so subsequent requests are made on demand.

get_assignment(assignment_id, response_groups=None)

Retrieves an assignment using the assignment’s ID. Requesters can only retrieve their own assignments, and only assignments whose related HIT has not been disposed.

The returned ResultSet will have the following attributes:

This element is present only if the Request ResponseGroup is specified.
The assignment. The response includes one Assignment object.
The HIT associated with this assignment. The response includes one HIT object.
get_assignments(hit_id, status=None, sort_by='SubmitTime', sort_direction='Ascending', page_size=10, page_number=1, response_groups=None)

Retrieves completed assignments for a HIT. Use this operation to retrieve the results for a HIT.

The returned ResultSet will have the following attributes:

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, as a string.
The number of the page in the filtered results list being returned. A positive integer, as a string.
The total number of HITs in the filtered results list based on this call. A non-negative integer, as a string.

The ResultSet will contain zero or more Assignment objects

get_file_upload_url(assignment_id, question_identifier)

Generates and returns a temporary URL to an uploaded file. The temporary URL is used to retrieve the file as an answer to a FileUploadAnswer question, it is valid for 60 seconds.

Will have a FileUploadURL attribute as per the API Reference.

get_help(about, help_type='Operation')

Return information about the Mechanical Turk Service operations and response group NOTE - this is basically useless as it just returns the URL of the documentation

help_type: either ‘Operation’ or ‘ResponseGroup’

get_hit(hit_id, response_groups=None)
static get_keywords_as_string(keywords)

Returns a comma+space-separated string of keywords from either a list or a string

static get_price_as_price(reward)

Returns a Price data structure from either a float or a Price

get_qualification_requests(qualification_type_id, sort_by='Expiration', sort_direction='Ascending', page_size=10, page_number=1)

TODO: Document.

get_qualification_score(qualification_type_id, worker_id)

TODO: Document.

get_qualifications_for_qualification_type(qualification_type_id, page_size=100, page_number=1)
get_reviewable_hits(hit_type=None, status='Reviewable', sort_by='Expiration', sort_direction='Ascending', page_size=10, page_number=1)

Retrieve 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.

grant_bonus(worker_id, assignment_id, bonus_price, reason)

Issues a payment of money from your account to a Worker. To be eligible for a bonus, the Worker must have submitted results for one of your HITs, and have had those results approved or rejected. This payment happens separately from the reward you pay to the Worker when you approve the Worker’s assignment. The Bonus must be passed in as an instance of the Price object.

grant_qualification(qualification_request_id, integer_value=1)

TODO: Document.

notify_workers(worker_ids, subject, message_text)

Send a text message to workers.

register_hit_type(title, description, reward, duration, keywords=None, approval_delay=None, qual_req=None)

Register a new HIT Type title, description are strings reward is a Price object duration can be a timedelta, or an object castable to an int

reject_assignment(assignment_id, feedback=None)
revoke_qualification(subject_id, qualification_type_id, reason=None)

TODO: Document.

search_hits(sort_by='CreationTime', sort_direction='Ascending', page_size=10, page_number=1, response_groups=None)

Return a page of a Requester’s HITs, on behalf of the Requester. The operation returns HITs of any status, except for HITs that have been disposed with the DisposeHIT operation. Note: The SearchHITs operation does not accept any search parameters that filter the results.

search_qualification_types(query=None, sort_by='Name', sort_direction='Ascending', page_size=10, page_number=1, must_be_requestable=True, must_be_owned_by_caller=True)

TODO: Document.

send_test_event_notification(hit_type, url, event_types=None, test_event_type='Ping')

Performs a SendTestEventNotification operation with REST notification for a specified HIT type

set_email_notification(hit_type, email, event_types=None)

Performs a SetHITTypeNotification operation to set email notification for a specified HIT type

set_rest_notification(hit_type, url, event_types=None)

Performs a SetHITTypeNotification operation to set REST notification for a specified HIT type

set_reviewing(hit_id, revert=None)

Update a HIT with a status of Reviewable to have a status of Reviewing, or reverts a Reviewing HIT back to the Reviewable status.

Only HITs with a status of Reviewable can be updated with a status of Reviewing. Similarly, only Reviewing HITs can be reverted back to a status of Reviewable.

set_sqs_notification(hit_type, queue_url, event_types=None)

Performs a SetHITTypeNotification operation so set SQS notification for a specified HIT type. Queue URL is of form:<CUSTOMER_ID>/<QUEUE_NAME> and can be found when looking at the details for a Queue in the AWS Console

unblock_worker(worker_id, reason)

Unblock a worker from working on my tasks.

update_qualification_score(qualification_type_id, worker_id, value)

TODO: Document.

update_qualification_type(qualification_type_id, description=None, status=None, retry_delay=None, test=None, answer_key=None, test_duration=None, auto_granted=None, auto_granted_value=None)
exception boto.mturk.connection.MTurkRequestError(status, reason, body=None)

Error for MTurk Requests

class boto.mturk.connection.Qualification(connection)

Class to extract an Qualification structure from a response (used in ResultSet)

Will have attributes named as per the Developer Guide such as QualificationTypeId, IntegerValue. Does not seem to contain GrantTime.

class boto.mturk.connection.QualificationRequest(connection)

Class to extract an QualificationRequest structure from a response (used in ResultSet)

Will have attributes named as per the Developer Guide, e.g. QualificationRequestId, QualificationTypeId, SubjectId, etc

endElement(name, value, connection)
class boto.mturk.connection.QualificationType(connection)

Class to extract an QualificationType structure from a response (used in ResultSet)

Will have attributes named as per the Developer Guide, e.g. QualificationTypeId, CreationTime, Name, etc

class boto.mturk.connection.QuestionFormAnswer(connection)

Class to extract Answers from inside the embedded XML QuestionFormAnswers element inside the Answer element which is part of the Assignment and QualificationRequest structures

A QuestionFormAnswers element contains an Answer element for each question in the HIT or Qualification test for which the Worker provided an answer. Each Answer contains a QuestionIdentifier element whose value corresponds to the QuestionIdentifier of a Question in the QuestionForm. See the QuestionForm data structure for more information about questions and answer specifications.

If the question expects a free-text answer, the Answer element contains a FreeText element. This element contains the Worker’s answer

NOTE - currently really only supports free-text and selection answers

endElement(name, value, connection)


class boto.mturk.layoutparam.LayoutParameter(name, value)

Representation of a single HIT layout parameter

class boto.mturk.layoutparam.LayoutParameters(layoutParameters=None)


Provides NotificationMessage and Event classes, with utility methods, for implementations of the Mechanical Turk Notification API.

class boto.mturk.notification.Event(d)
class boto.mturk.notification.NotificationMessage(d)

Constructor; expects parameter d to be a dict of string parameters from a REST transport notification message

EVENT_PATTERN = 'Event\\.(?P<n>\\d+)\\.(?P<param>\\w+)'
EVENT_RE = <_sre.SRE_Pattern object>
SERVICE_NAME = 'AWSMechanicalTurkRequesterNotification'

Verifies the authenticity of a notification message.

TODO: This is doing a form of authentication and
this functionality should really be merged with the pluggable authentication mechanism at some point.


class boto.mturk.price.Price(amount=0.0, currency_code='USD')
endElement(name, value, connection)
get_as_params(label, ord=1)
startElement(name, attrs, connection)


class boto.mturk.qualification.AdultRequirement(comparator, integer_value, required_to_preview=False)

Requires workers to acknowledge that they are over 18 and that they agree to work on potentially offensive content. The value type is boolean, 1 (required), 0 (not required, the default).

class boto.mturk.qualification.LocaleRequirement(comparator, locale, required_to_preview=False)

A Qualification requirement based on the Worker’s location. The Worker’s location is specified by the Worker to Mechanical Turk when the Worker creates his account.

class boto.mturk.qualification.NumberHitsApprovedRequirement(comparator, integer_value, required_to_preview=False)

Specifies the total number of HITs submitted by a Worker that have been approved. The value is an integer greater than or equal to 0.

If specifying a Country and Subdivision, use a tuple of valid ISO 3166 country code and ISO 3166-2 subdivision code, e.g. (‘US’, ‘CA’) for the US State of California.

When using the ‘In’ and ‘NotIn’, locale should be a list of Countries and/or (Country, Subdivision) tuples.

class boto.mturk.qualification.PercentAssignmentsAbandonedRequirement(comparator, integer_value, required_to_preview=False)

The percentage of assignments the Worker has abandoned (allowed the deadline to elapse), over all assignments the Worker has accepted. The value is an integer between 0 and 100.

class boto.mturk.qualification.PercentAssignmentsApprovedRequirement(comparator, integer_value, required_to_preview=False)

The percentage of assignments the Worker has submitted that were subsequently approved by the Requester, over all assignments the Worker has submitted. The value is an integer between 0 and 100.

class boto.mturk.qualification.PercentAssignmentsRejectedRequirement(comparator, integer_value, required_to_preview=False)

The percentage of assignments the Worker has submitted that were subsequently rejected by the Requester, over all assignments the Worker has submitted. The value is an integer between 0 and 100.

class boto.mturk.qualification.PercentAssignmentsReturnedRequirement(comparator, integer_value, required_to_preview=False)

The percentage of assignments the Worker has returned, over all assignments the Worker has accepted. The value is an integer between 0 and 100.

class boto.mturk.qualification.PercentAssignmentsSubmittedRequirement(comparator, integer_value, required_to_preview=False)

The percentage of assignments the Worker has submitted, over all assignments the Worker has accepted. The value is an integer between 0 and 100.

class boto.mturk.qualification.Qualifications(requirements=None)
class boto.mturk.qualification.Requirement(qualification_type_id, comparator, integer_value=None, required_to_preview=False)

Representation of a single requirement



class boto.mturk.question.AnswerSpecification(spec)
template = '<AnswerSpecification>%(spec)s</AnswerSpecification>'
class boto.mturk.question.Application(width, height, **parameters)
parameter_template = '<Name>%(name)s</Name><Value>%(value)s</Value>'
template = '<Application><%(class_)s>%(content)s</%(class_)s></Application>'
class boto.mturk.question.Binary(type, subtype, url, alt_text)
template = '<Binary><MimeType><Type>%(type)s</Type><SubType>%(subtype)s</SubType></MimeType><DataURL>%(url)s</DataURL><AltText>%(alt_text)s</AltText></Binary>'
class boto.mturk.question.Constraint
class boto.mturk.question.Constraints
template = '<Constraints>%(content)s</Constraints>'
class boto.mturk.question.ExternalQuestion(external_url, frame_height)

An object for constructing an External Question.

schema_url = ''
template = '<ExternalQuestion xmlns=""><ExternalURL>%(external_url)s</ExternalURL><FrameHeight>%(frame_height)s</FrameHeight></ExternalQuestion>'
class boto.mturk.question.FileUploadAnswer(min_bytes, max_bytes)
template = '<FileUploadAnswer><MaxFileSizeInBytes>%(max_bytes)d</MaxFileSizeInBytes><MinFileSizeInBytes>%(min_bytes)d</MinFileSizeInBytes></FileUploadAnswer>'
class boto.mturk.question.Flash(url, *args, **kwargs)
class boto.mturk.question.FormattedContent(content)
schema_url = ''
template = '<FormattedContent><![CDATA[%(content)s]]></FormattedContent>'
class boto.mturk.question.FreeTextAnswer(default=None, constraints=None, num_lines=None)
template = '<FreeTextAnswer>%(items)s</FreeTextAnswer>'
class boto.mturk.question.HTMLQuestion(html_form, frame_height)
schema_url = ''
template = '<HTMLQuestion xmlns=""><HTMLContent><![CDATA[<!DOCTYPE html>%(html_form)s]]></HTMLContent><FrameHeight>%(frame_height)s</FrameHeight></HTMLQuestion>'
class boto.mturk.question.JavaApplet(path, filename, *args, **kwargs)
class boto.mturk.question.LengthConstraint(min_length=None, max_length=None)
attribute_names = ('minLength', 'maxLength')
template = '<Length %(attrs)s />'
class boto.mturk.question.List

A bulleted list suitable for OrderedContent or Overview content

class boto.mturk.question.NumberOfLinesSuggestion(num_lines=1)
template = '<NumberOfLinesSuggestion>%(num_lines)s</NumberOfLinesSuggestion>'
class boto.mturk.question.NumericConstraint(min_value=None, max_value=None)
attribute_names = ('minValue', 'maxValue')
template = '<IsNumeric %(attrs)s />'
class boto.mturk.question.OrderedContent
append_field(field, value)
class boto.mturk.question.Overview
template = '<Overview>%(content)s</Overview>'
class boto.mturk.question.Question(identifier, content, answer_spec, is_required=False, display_name=None)
template = '<Question>%(items)s</Question>'
class boto.mturk.question.QuestionContent
template = '<QuestionContent>%(content)s</QuestionContent>'
class boto.mturk.question.QuestionForm

From the AMT API docs:

The top-most element of the QuestionForm data structure is a QuestionForm element. This element contains optional Overview elements and one or more Question elements. There can be any number of these two element types listed in any order. The following example structure has an Overview element and a Question element followed by a second Overview element and Question element–all within the same QuestionForm.

<QuestionForm xmlns="[the QuestionForm schema URL]">

QuestionForm is implemented as a list, so to construct a QuestionForm, simply append Questions and Overviews (with at least one Question).

schema_url = ''
xml_template = '<QuestionForm xmlns="">%(items)s</QuestionForm>'
class boto.mturk.question.RegExConstraint(pattern, error_text=None, flags=None)
attribute_names = ('regex', 'errorText', 'flags')
template = '<AnswerFormatRegex %(attrs)s />'
class boto.mturk.question.SelectionAnswer(min=1, max=1, style=None, selections=None, type='text', other=False)

A class to generate SelectionAnswer XML data structures. Does not yet implement Binary selection options.

ACCEPTED_STYLES = ['radiobutton', 'dropdown', 'checkbox', 'list', 'combobox', 'multichooser']
MAX_SELECTION_COUNT_XML_TEMPLATE = '<MaxSelectionCount>%s</MaxSelectionCount>'
MIN_SELECTION_COUNT_XML_TEMPLATE = '<MinSelectionCount>%s</MinSelectionCount>'
SELECTIONANSWER_XML_TEMPLATE = '<SelectionAnswer>%s%s<Selections>%s</Selections></SelectionAnswer>'
SELECTION_XML_TEMPLATE = '<Selection><SelectionIdentifier>%s</SelectionIdentifier>%s</Selection>'
STYLE_XML_TEMPLATE = '<StyleSuggestion>%s</StyleSuggestion>'
class boto.mturk.question.SimpleField(field, value)

A Simple name/value pair that can be easily rendered as XML.

>>> SimpleField('Text', 'A text string').get_as_xml()
'<Text>A text string</Text>'
template = '<%(field)s>%(value)s</%(field)s>'
class boto.mturk.question.ValidatingXML
class boto.mturk.question.XMLTemplate