How do I set up and troubleshoot an automated Retrieve Task

You can run Retrieve on a scheduled basis using the Windows task scheduler

NOTE: DocuSign monitors usage of this application very closely. DocuSign Retrieve should not be used at an interval more frequent than once per hour. Running DocuSign Retrieve on an interval shorter than one hour can result in revoked access to the Retrieve application. If you are needing a service with real time results and retrieval of DocuSign documents, envelopes, and statuses, DocuSign Connect should be used in place of Retrieve. For more information, see Agreement Actions, DocuSign Retrieve, or DocuSign Connect: When to Use Which Solution.

Note: The DocuSign Customer Support team supports DocuSign products, such as Retrieve, but it is not set up to provide custom workflow support. Our Support teams are not trained for providing custom workflows. If additional assistance is needed please request a Professional Services engagement.

Getting Started




Task Scheduler fails while CMD works​
  • Check the Action section of the Windows task. Ensure that program path hasn’t defaulted to DocuSignRetrieveApp.exe
  • If using Windows Server 2008 R2 or 2016, you may need to set the compatibility mode for the executable as well as the task to Windows 7.
  • Open the task, go to the Actions tab and click Edit. Ensure that the directory for the Retrieve app is included in the Start in (optional) line with quotation marks removed
Task Scheduler succeeds with no error but no files are downloaded
  • Enable hidden files / folders. Navigate to the target download folder and delete the .downloaded folder. This is how Retrieve tracks items that have already been downloaded.
  • In the Task Scheduler, open the task and go to the General Tab. Towards the middle under Security options, ensure the user / group is the same user that has authenticated with Retrieve started as an Administrator
Task Scheduler automatically selects a different executable
  • Ensure that you are using the most current version of Retrieve. 3.2.2 or older version may result in the incorrect executable being selected, you can either upgrade to the latest version or specify DocuSignRetrieve.exe.
Task configuration is incorrect
  • Check the program/script section of the Actions tab is DocuSignRetrieve.exe.
  • The rest of the script block needs to be added to the Add arguments section.
  • The script uses multiple quotation marks which can result in syntax errors when the task launches.
XML access error

ERROR: The task XML contains a value which is incorrectly formatted or out of range.
  • Confirm latest version of Retrieve.
  • Try uninstall and reinstall Retrieve.
Compatibility settings issue

Some versions of Windows will require that compatibility mode be enabled for Retrieve. Locate the Retrieve shortcut, right click on it, then click Properties | Compatibility tab.
Click "Run this program in compatibility mode for", then select Windows 7. Hit Apply, then run the task again.

Note that the General section of the task also has a compatibility setting, this will need to be changed to Windows 7.

User-added image
User-added image
401 access violation
  • 401 access violation means that the login credentials supplied are invalid. Correcting these credentials should allow the task to continue running. Keep in mind that in order to download envelopes from all users you’ll need to log in with an account administrator’s credentials.
Missing envelopes

Typically this indicates that your account has gone over its hourly API call limit. By default accounts are restricted to 1000 calls per hour. Retrieve makes multiple calls per envelope with a minimum of 5 along with several overhead calls.

If your CSV includes Envelope Custom Fields it can increase the required number of calls per envelope. Because of this the typical maximum number of envelopes downloaded per Retrieve query is going to be between 165 and 198 envelopes per hour. If you exceed this number there will likely not be a warning provided but the envelopes you’re looking for may appear to be missing.

The easiest way to correct this is to change the frequency of your task to execute more than once per day. 

Do I need to change my scheduled task after updating to Retrieve 3.3.1?

The 3.3.1 version of Retrieve no longer uses username and password combinations to authenticate -- it now relies on OAuth tokens. The tokens are stored locally on your PC after successfully logging in as an Administrator on the Local PC. If a username and password are still supplied as part of the task, Retrieve will see this as a deprecated parameter and ignore it -- this should not stop the task from executing.


Failed to initialize or connect. Error: Unable to obtain a previously stored DocuSign authentication token. To get a new authentication token, use 'DocuSignRetrieveApp.exe' to complete your DocuSign login. Error: Failed to obtain token data from Windows Credential Manager for DocuSign Retrieve

In order to retrieve the OAuth token the token needs to be stored on your machine. In order for this to happen Retrieve needs to be opened as an Administrator on the Local PC. The token itself is stored in your system registry and will require administrative credentials to write it there.

Any Status, Compatibility