SOAP API supportability, query thresholds, and latency

IMPORTANT  The SOAP API entered a limited enhancement phase in Q4 2020. Access to version 1.6 will eventually be deactivated. At this time, there is no end-of-lifecycle date.

This article describes the limits of supportability and data rate thresholds that apply to the SOAP API.

Please note that while Autotask provides a Web Services API that is available to all customers, development tools are not intended for use by the general public.

Datto Technical Support will make sure that any errors you receive are not the result of a bug. However, we will not assist you with the creation or troubleshooting of your application code. Refer to If you find a defect in the API...

We encourage you to reach out to other developers via Datto Community Portal. And if you're a seasoned API user, visit the Community and share your knowledge with other users.

The API User (API-only) system security level provides full system administrator access to Autotask modules, features, and data. However, copies of the system security level can be modified to restrict access to certain modules, features, and data. As a result, the API user with a restricted license would get no response to an API call, even though the data exists in your database.

EXAMPLE  The API user is unable to retrieve an invoice even though the invoice ID exists in your database, because the API user is not assigned to the line of business with which the invoice is associated.

You can include up to 500 OR conditions in a single call to the API. If a call contains more than 500 OR statements, you will receive the API response, "Invalid query syntax. Queries are limited to 500 or fewer 'OR' conditions."

To ensure an acceptable response time for all Web Services API users and prevent inadvertent coding errors from crippling the system, Autotask sets a limit of 10,000 on the number of external requests allowed per hour between an individual database and the API. That is, on receipt of a request, the API will check the number of requests received for that database (counting all integrations) in the preceding 60 minutes. In addition, a usage based latency is applied as you approach the threshold, and you will receive a notification.

The threshold is generous and you should not see an impact with normal API usage.

It is possible to reach the threshold, however, if you are running multiple high usage integrations or one integration that is calling the API on multiple threads. If you should actually reach the threshold, API service is temporarily suspended, and an error message is generated.

Who receives API Threshold Exceeded notifications?

In addition to the error message returned through the API, Autotask sends an email notification if usage exceeds the API threshold. The following order of preference applies:

  1. If you set up an "Unsuccessful Ticket Creation" email address for an ATES mailbox configured to receive human-readable notifications, then Autotask will send a warning to that email. If you configured multiple addresses, the application will send a warning notification to all of them.
  2. If Autotask cannot find the email address described above, it will send the warning to your Support email address.
  3. If the application cannot find a Support email address, it will send the warning to the primary email address of the API user responsible for the violation.

You can view API activity and threshold information by using the API Activity by Hour report in Autotask.

You can use the API call getThresholdAndUsageInfo() to determine your database threshold and monitor how close you are to reaching it. For details about this call, refer to getThresholdAndUsageInfo().

As you approach your threshold, the Web Services API will add a usage-based latency. The latency is calculated to prevent the number of calls within an hour from reaching the threshold amount. This preferred model allows applications to continue processing rather than being interrupted by a suspension of service.

The latency is based on the number of requests submitted, as a percentage of the number of requests allowed, as follows:

0-49.99%, latency = 0 sec

50.00-74.99%, latency = .5 sec

75.00+%, latency = 1 sec

EXAMPLE  If the threshold = 10,000 requests per hour, at 5,000 requests the API will add .5 seconds to each request up to 7,499. At 7,500 requests, the latency increases to 1 second.

To ensure a consistent quality of service for all users, the API uses the following thresholds when processing attachments:

  • The maximum attachment file size indicated in the Autotask Online Help does not apply to the API. The API size limit for individual attachment files is 6 to 7 MB, with a maximum of 10,000,000 bytes within a five-minute period. If your integration exceeds either of these limits, you'll receive an error message indicating condition. If the integration exceeds 10,000,000 bytes within a five-minute span, the API will also stop accepting attachment creation calls for five minutes.

NOTE  The API size limit for individual attachments is less than the 10 MB limit for individual attachment files when working through the Autotask UI.

  • Attachment types are limited to the file types allowed in Autotask. For more details, refer to Add attachments.

Limits on simultaneous API execution threads and multi-thread latency apply to the Autotask web services API. For important details about how they impact integration development, review our API thread limiting article.

To prevent an inadvertent coding error from consuming too many server resources, Autotask has set a five-minute execution timeout for all Web Services API calls.

In addition to an error message returned through the API, Autotask sends an email notification if usage exceeds the threshold. The following order of preference applies.

  1. If you have set up an Unsuccessful Ticket Creation email address for your ATES mailbox under Incoming Email Processing, and that address is configured to receive human-readable notifications, the warning is sent to that email address. If multiple addresses are configured, we will send to all of them.
  2. If the email address described above is not found, the email is sent to your Support Email Address.
  3. If no Support Email Address is found, the email is sent to the primary email address of the API user responsible for the violation.

On query, the Autotask API returns no more than 500 records per entity at once, sorted by internal ID from lowest to highest. If your query is likely to return over 500 records, and you want to receive all of those records, you must create looping queries. Set up queries where each query filters for an id value that is greater than the maximum value received in the previous query.

Whenever possible, use strong filters to limit the number of records that the API returns. Doing so can improve performance when driving a user interface directly from the API.

Unless otherwise noted, API entities do not support the creation or editing of Rich Text content. If an unsupported entity receives a request to update a field that contains Rich Text, the API will update the text-only version of the field and overwrite the data in the Rich Text field with plain text.

When querying a field that has Rich Text, the API will return the text-only version of the field. If the user sends content back to an unsupported entity, the Rich Text and all images it contains will be lost. You cannot use the API to create items that contain Rich Text, but you can add Rich Text later via a supported method.

To learn more, refer to The Rich Text editor.