Amazon Mechanical Turk

Mturk Add Assignments

Add more assignments to an existing HIT so additional workers can accept it. Useful when the first worker's submission was low quality and you want another attempt, or when you need more consensus responses. The HIT must still be active (not expired/deleted). List your HITs to find active HIT IDs.

Mturk Approve Assignment

Approve a worker's assignment, releasing the HIT reward payment to them. Only works on assignments with status 'Submitted'. Optionally include feedback the worker will see. List submitted assignments on the HIT to find IDs awaiting review.

Mturk Assign Qualification

Grant a qualification to a specific worker. Use this to build a pool of trusted workers — grant a custom qualification to good performers, then require it on future HITs. Also used to update a worker's qualification score (call again with a different integer_value). Worker IDs appear on assignment records.

Mturk Block Worker

Block a worker from accepting any of your future HITs. Use for workers who submit spam, gibberish, or consistently low-quality work. The worker is NOT notified of the block and cannot see the reason. Unblock later from your blocked-workers list.

Mturk Create Hit

Create a new Human Intelligence Task (HIT) on Amazon Mechanical Turk. Provide a title, description, step-by-step instructions, and reward amount. Workers will see a form with the instructions and a text input to paste their answer. For custom forms (file uploads, multiple fields, etc.), pass custom_html instead. Returns the HIT ID for tracking. List assignments on that HIT after workers submit.

Mturk Create Qualification

Create a custom qualification type for screening and targeting workers. After creating, grant it to specific workers, then reference the qualification_type_id when creating HITs to restrict who can accept them. Set auto_granted=true to let any worker who requests the qualification receive it automatically.

Mturk Delete Hit

Delete or expire a HIT from your MTurk account. Set expire_only=true to remove the HIT from the marketplace without deleting it (useful if assignments are still pending). Set expire_only=false to permanently delete (HIT must have no pending assignments). List your HITs to find HIT IDs.

Mturk Delete Qualification

Delete a custom qualification type you created. This removes the qualification from all workers who had it. HITs requiring this qualification will no longer be restricted by it. Cannot delete system qualifications (approval rate, locale, etc.).

Mturk Get Assignments

Get worker submissions for a HIT. Only returns assignments that workers have SUBMITTED — accepted-but-unfinished work is NOT visible here (list HITs and check assignments_pending to see how many workers are currently working). Returns each assignment with the worker's answers parsed from XML into a readable dict, plus status (Submitted, Approved, Rejected). Use status='Submitted' to find assignments awaiting review, then approve or reject each one.

Mturk Get Balance

Get your MTurk Requester account balance. MTurk costs are billed through AWS Billing — there is no prepay step. In sandbox mode, returns $10,000.00 (test balance).

Mturk Get Blocked Workers

List workers you have blocked from accepting your HITs. Returns worker IDs and the reason you blocked them. Unblock a worker when you want them to accept HITs again.

Mturk Get Hits

Get HITs from your MTurk account. Pass hit_id to retrieve a single HIT with full details, or omit to list all your HITs with status, assignment counts, and reward info. Key fields: assignments_available (open slots), assignments_pending (workers currently working but not yet submitted — the only way to see in-progress work), assignments_completed (submitted). Use next_token for pagination through large result sets.

Mturk Get Qualifications

Get qualification types from your MTurk account. Pass qualification_type_id for a specific one, or search with query text. Set must_be_owned_by_caller=false to include system qualifications (like approval rate, locale, etc.). If the response includes a next_token, pass it in a follow-up call to get the next page.

Mturk Get Qual Requests

List pending qualification requests from workers for a specific qualification type. Workers request qualifications when they want to work on HITs that require them. Review requests and accept or reject each one. If the response includes a next_token, pass it in a follow-up call to get the next page.

Mturk Get Reviewable Hits

List HITs that have worker submissions waiting for your review. This is the best way to find HITs that need attention — more efficient than listing all HITs and checking each for assignments. Returns HIT IDs; list assignments for each HIT ID to read the submissions.

Mturk List Bonus Payments

List bonus payments you've sent to workers. Filter by hit_id or assignment_id to see bonuses for specific work. Returns payment amounts, worker IDs, and reasons. Provide either hit_id or assignment_id (at least one is required by the API). If the response includes a next_token, pass it in a follow-up call to get the next page.

Mturk List Qualified Workers

List workers who have a specific qualification, along with their score. Useful for seeing your pool of qualified workers for a given task type. If the response includes a next_token, pass it in a follow-up call to get the next page.

Mturk Notify Workers

Send an email notification to one or more MTurk workers. Useful for follow-up instructions, clarifications, or thanking workers. Max 100 workers per call. The email is sent via MTurk's notification system. Worker IDs appear on assignment records.

Mturk Reject Assignment

Reject a worker's assignment — the worker will NOT be paid. Use sparingly; rejections hurt the worker's approval rate. Only reject for clearly invalid submissions (wrong answer, spam, didn't follow instructions). A reason is required and the worker will see it. List submitted assignments on the HIT to find IDs awaiting review.

Mturk Reject Qual Request

Reject a worker's qualification request. The worker will not receive the qualification and cannot accept HITs that require it. Provide a reason — the worker sees it.

Mturk Revoke Qualification

Remove a qualification from a worker. The worker will no longer be able to accept HITs that require this qualification. An optional reason message is shown to the worker.

Mturk Send Bonus

Send a bonus payment to a worker on top of the HIT reward. Useful for rewarding workers who do exceptional work or go beyond instructions. The bonus is billed through AWS Billing along with HIT rewards and fees. Use worker_id and assignment_id from an approved assignment.

Mturk Unblock Worker

Remove a block on a worker, allowing them to accept your HITs again. List blocked workers to see your block list.

Mturk Update Expiration

Change when a HIT expires. Extend the deadline to give workers more time, or set it to a past date to immediately remove the HIT from the marketplace (without deleting it). The HIT must still exist. List your HITs to see current expiration times.