Amazon Mechanical Turk
Requester UI Guide (API Version 2017-01-17)

How to Create a Project

You must create a Mechanical Turk project before you can create a batch of HITs. This section shows you how to create a Mechanical Turk project.

The Mechanical Turk project contains the HTML of your HIT page as well as meta-data about the HIT, called HIT properties, such as the expiration date of the HIT. To create a project, start with one of the provided sample project templates and customize it.

The following procedure describes in detail how to create a project using the “Tagging of an image" sample project. This procedure is identical for all other sample projects with the exception of Categorization and Sentiment projects. For information about Categorization projects, see How to Create a Categorization Project. For information about Sentiment projects, see How to Create a Sentiment Project.

The following are the overall steps you need to take when creating a Mechanical Turk project.

  • Define the projects properties.

  • Design the project's HTML layout.

  • Preview the project.

The following procedure describes in detail how to create a project using the Tagging of an Image sample project. For our project, let's assume you have a large number of images that you want to tag with geographical locations and landmarks. In the procedure, you will create a HIT using the Tagging of an Image sample project, customize it to provide your images, and then modify the input fields to collect this set of information from the Workers.

To create a project

  1. On the Mechanical Turk Requester website, click the Create tab and then click New Project.

  2. From the list under Start a New Project, select a sample project and click Create Project. For example, click on Tagging of an Image and then click Create Project.

    Create Tab - Tagging of an Image project selected
  3. On the Edit Project page, the tabs Enter Properties, Design Layout, and Preview and Finish, guide you through the process of preparing a project.

    Edit Project Tabs
  4. On the Edit Properties tab of the Edit Project page, fill in the property entry fields according to the specifics of your HIT.

    1. Fill in the Project Name and the property entry fields in the Describe your HIT to Workers section of the page.

      Edit Project Tabs

      The following table describes the Project Name field and the property entry fields for the Describe your HIT to Workers section of the Edit Properties tab.

      Field Description
      Project Name The project name field is filled in, but you can change it. Make sure the project name is descriptive so that you can easily identify the project when you want to publish a batch with the project. The project name is not displayed to Workers.
      Title Enter the name of the HIT. Be specific. For example, enter "Tag landmark images" instead of "Tag photos." The title is displayed to Workers.
      Description Describe the HIT. The search mechanism searches using this description so use words that you think will help Workers find your HITs.
      Keywords Enter a comma-separated list of words that Workers can use to find your HIT.
    2. Fill in the property entry fields in the Setting up your HIT section of the page.

      The following list describes the property entry fields for the Setting up your HIT section of the Edit Properties tab.

      Field Description
      Reward per assignment Specify how much money you'll pay the Worker if you approve an assignment.
      Number of assignments per HIT

      Specify the number of unique Workers you want to work on each HIT. One assignment per HIT means that only one Worker works on a HIT. You might want multiple Workers to work on a HIT to see if there is agreement between Workers, which can increase your trust in the results.

      A Worker can only accept a HIT once and can only submit one assignment per HIT. This guarantees that multiple Workers must complete a HIT that has multiple assignments.

      Time Allotted Per Assignment Specify how long the Worker can hold on to individual assignments within your batch to work on them. Once this time has passed, the HITs are withdrawn from the Worker so others can work on them.
      HIT expires in

      Specify how long Workers can accept HITs in the batch. Workers can't accept HITs in the batch once this time expires. Workers can finish working on assignments they previously accepted even though the batch is no longer available for others to work on.

      Auto-approve and pay Workers in Specify when Amazon Mechanical Turk will automatically approve your HITs and pay Workers. This determines the amount of time you have to reject an assignment submitted by a Worker before the assignment is auto-approved and the Worker is paid. This limit ensures that Workers get paid in a timely manner.
  5. When you are done filling in the property fields on the Edit Project page, click the Design Layout button.

  6. On the Design Layout tab of the Edit Project page, use the controls in the formatting toolbar to edit the text on the page.

    Design Layout
  7. Click Source to add variables to the HTML source.

    Design Layout - HTML Edit

    You will add two variables to your design to supply the Uniform Resource Locator (URL) and continent description for your image. The variables are replaced by the data from a HIT data file when you publish your HIT. For information about publishing your HIT, see Publishing a Batch. You define a variable by using a dollar sign ($) and then surrounding the name of your variable with curly brackets. The following table describes the three different variable types you can use in your HIT design.

    Variable Type Format

    Use to add text from a HIT data file.

    Define using a dollar sign ($) and curly brackets. For example: ${text}


    Use to add images from a HIT data file.

    Define using a dollar sign ($) and curly brackets in a HTML image tag, <img>. For example:

    <img width="200" height="200" alt="image1" style="margin-right: 10px;" src="${image_url}"/>


    Use to add links from a HIT data file to audio and video files, and websites.

    Define using a dollar sign ($) and curly brackets in a HTML href tag, <href>. For example:

    <p>Video link: <b><a target="_blank" href="${link}">${link}</a></b></p>

  8. Add the following HTML code that contains the ${continent} and ${image_url} variables.

    <p>This landmark is in ${continent}.</p> <p><img width="200" height="200" alt="image1" style="margin-right: 10px;" src="${image_url}"/></p>
  9. Create your HIT data file.

    The HIT data file is a comma-separated-value .csv file that contains the data values used to replace your variables. Many spreadsheet applications, including Microsoft Excel, can save files in the .csv file format.

    Each new line in the file represents a new HIT. The number of data values in one row should exactly match the number of values used in your project. The first row in the .csv HIT data file contains the column headings for the data value columns. The order in which you use the variables in the project template does not need to match the order of columns in the .csv file.

    The names of the template variables must match the column headings for the values in your HIT data file. For example, since we used the ${continent} variable, our HIT data file must have a column that has the continent heading.

    Tag This Image

    Your HIT data file cannot have line breaks between data cells and "\r" is not supported as a line break character. Apple Macintosh computers insert this character when they convert a Microsoft Excel table into a .csv file.

    If your HITs contain images or videos, you must include links to them in the HIT data file, and the images and videos must be publicly accessible. The user interface does not provide a tool for uploading images or videos. Consider using one of the publicly-available tools to upload your images into Amazon S3.

  10. Create two input fields in your template, named Landmark and Country, where Workers can enter the answers for a HIT.

    You must include the HTML name attribute in the input field definition. Make your name attributes descriptive because they are used as the column headings in the Results table.

    The following example shows an HTML table that has two input fields, Landmark and Country, which both have a size of 25.

    <table cellspacing="4" cellpadding="0" border="0"> <tbody> <tr> <td valign="center"> <p>Landmark</p> <input type="text" name="Landmark" id="Field1" size="25" /></td> <td valign="center"> <p>Country</p> <input type="text" name="Country" id="Field2" size="25" /></td> </tr> </tbody> </table>

    The Amazon Mechanical Turk returns results in a table that is stored in a comma-separated-value .csv file. The number of input and answer fields in one HIT determines the number of columns in the Results table. One row in the Results table represents a complete set of answers for one HIT as shown in the following example.

    Results Spreadsheet
  11. Delete any code that you don't need and then click Save to save the HTML of your project.

    Amazon Mechanical Turk deletes a project if you don't use the project for 120 consecutive days. If you need to access your project for a longer period of time, we recommend that you copy the HTML and save it on your own system.

  12. Click Source to exit the HTML source. Review your changes. If you are satisfied with your changes, click Preview.

  13. On the Preview and Finish tab of the Edit Project page, click Finish.

After you click Finish, the Create page displays and your project appears in your list of existing projects.

You have set the HIT properties for all of the HITs in your batch and designed the HTML page that Workers working on your HITs will see. Now, you need to publish the batch to make it available to Workers. For information about publishing a batch, see Publishing a Batch.