MATLAB toolbox for communicating with Amazon's Mechanical Turk (AMT) API.
Matlab M Objective-C
Switch branches/tags
Nothing to show
Clone or download
Latest commit 4e933ce Sep 23, 2015
Failed to load latest commit information.
demo Update GatherResults.m Sep 4, 2015
mturkAPI Initial mturkMatlab commit Jan 21, 2015
util Updated various functions Jan 21, 2015
LICENSE Initial commit Jun 18, 2014 Update Sep 23, 2015
turkConfig.m Update turkConfig.m Sep 19, 2015

mturkMatlab: MATLAB Mechanical Turk Toolbox

Toolbox for MATLAB to communicate with Amazon's Mechanical Turk (MTurk) using the SOAP interface. The goal of this toolbox is to act as an alternative to the MTurk Command Line Tools allowing you to manage HITs and retrieve results, all while enjoying the comforts of MATLAB.

The toolbox is designed to be simple and easy to use and is largely modeled around providing the same functionality as Amazon's MTurk API. The function names and arguments are intentionally kept identical to the Operations from the MTurk API to provide a familiar interface for people currently using other toolboxes.

The toolbox works with MATLAB and has not been tested on Octave (please let me know if you find out either way!). Note: it seems that there are some inexplicable Java errors when using earlier versions of MATLAB (<=2012). Please upgrade your version of MATLAB if you encounter these.


All functions are written in MATLAB and no compilation is required. To download:

$ git clone

Basic usage

The basic usage is relatively simple:

$ cd mturkMatlab
$ matlab
>> addpath(genpath('.'));
>> aws_access_key = 'XXXXXXXXXX';           % access key from AWS
>> aws_secret_key = 'YYYYYYYYYY';           % secret key from AWS
>> sandbox = true;                          % run API functions on sandbox
>> turk = InitializeTurk(aws_access_key, aws_secret_key, sandbox);
>> [result, found_error] = GetAccountBalance(turk, GetAccountBalanceStruct());
>> disp(['Your balance is $' result.AvailableBalance.Amount]);

You can obtain your AWS access key and secret key from Amazon's console here.

The API functions in the toolbox such as CreateHIT or GetAccountBalance require 2 arguments:

  • turk: this is a structure containing basic information for all functions such as your access key and secret key, as well as whether the current commands are to be executed on Sandbox or not. The way to initialize this variable is shown above. Note that the structure contains other options that you can modify if you see fit.

  • Function struct: this is a structure that is specific to the function being called. If the API function to be called is Func(), then the structure associated with that function can be obtained by calling FuncStruct(). The value returned will contain a structure containing the set of arguments possible for that particular API function. You can modify these values before calling the API function. In many cases this structure will not require any modification, as in the example above. In the demo folder, there are various examples where this structure is modified before calling the API function.


There are a few demo scripts provided in the demo folder to help you get started. There are sample scripts for checking your balance, creating external HITs and approving and deleting all HITs.


The provided code was used for MTurk experiments in the following paper:

Please cite it if you use this code.

Questions and Comments

If you have any feedback, please email Aditya Khosla at

Also, pull requests of fixes/improvements are most welcome.


This toolbox is released under the MIT license. For additional details see LICENSE file.