Scalability options

Bulk Operations

The Smartsheet API supports a number of bulk operations that can operate on multiple objects. Unlike single-object operations, bulk operations allow you to create, update, or delete multiple objects in a single request. For example, if you want to update 10 rows within a sheet, do so using a single Update Rows request, rather than executing 10 separate requests - one for each row.

Optional Bulk Operations

Several endpoints support optional bulk POST operations which exist alongside the standard single-object POST. For these endpoints, you may pass in either a single object or an array of objects. Depending on what was passed in, the Result object returned contains either a single object or an array. An example optional bulk operation is POST /favorites: you can pass in a single Favorite object to create a single favorite, or an array of Favorite objects to create multiple favorites in a single request. Endpoints which support bulk operations are noted as such in the API reference documentation.

NOTE: Most POST operations fail when attempting to create a single object which already exists (for example, favorites, shares, group members). However, for the corresponding bulk operations, these endpoints do not return an error if one or more items in the array already exist. Existing items are simply ignored, and the Result object returned omits them.

Partial Success

In general, the default behavior for bulk operations is to fail outright if any of the objects in the request are invalid for some reason. If successful, Smartsheet creates/updates/deletes all objects in the request; if not, no objects are changed.

However, there are some operations that support partial success, which means the operation still succeeds even if one or more of the objects in the request fails for some reason (for example, an object is invalid). Here is another example: if you want to update more than one row, you send more than one row object in your request. If a row object is invalid, that row update will fail, but the other row updates will succeed. Partial success is not the default mode for an operation and you must explicitly enable it by using a query string parameter. This is noted in the documentation for operations that support partial success.

When partial success is enabled, and one or more of the objects in the request fail to be added/updated/deleted, a standard Result object is returned, but with a message of 'PARTIAL_SUCCESS' (instead of 'SUCCESS'), and a resultCode of 3. Additionally, the object contains a failedItems attribute -- an array of BulkItemFailure objects that contains an item for each object in the request that failed to be added/updated/deleted.

Rate limiting

To ensure the stability and reliability of our services, we enforce rate limits on our API. This protects our servers from excessive load and prevents potential abuse. The general limit for most API requests is 300 requests per minute per API token.

Important: Unless otherwise stated, an endpoint operation's rate limit is 300 requests per minute per API token.

Understanding request multipliers

Some API operations are more resource-intensive than others and are assigned a higher cost via a request multiplier. This means a single call to one of these endpoints counts as multiple requests against your overall limit. For these specific operations, a separate, lower rate limit applies to ensure server health.

• File attachments: Posting a file attachment is resource-intensive and has a multiplier of 10x. This operation is limited to 30 requests per minute per API token.
• Cell history: Fetching a cell's history also has a multiplier of 10x. Its limit is likewise 30 requests per minute per API token.
• All other operations: The vast majority of API requests have a multiplier of 1x and are subject to the standard limit of 300 requests per minute per API token.

Rate limit summary

The table below provides a quick overview of the rate limits for different API operations.

Handle "Rate limit exceeded" Error

When API calls exceed an acceptable load, an HTTP 429 status will be returned along with the following response body:

{
"errorCode": 4003,
"message": "Rate limit exceeded."
}

We recommend that you design your integration to gracefully handle this rate limit error. One way of doing that would be to have your integration sleep for a minimum of 60 seconds when this error is encountered, and then subsequently retry the request.

Alternatively, you might choose to implement exponential backoff (an error handling strategy whereby you periodically retry a failed request with progressively longer wait times between retries, until either the request succeeds or the certain number of retry attempts is reached). Note that the SDKs implement this behavior.

Avoid Executing "Rapid Fire" Updates

If the only thing your integration does is execute an Update Rows request once every second for the same sheet, that would only amount to a total of 60 requests per minute -- well within rate limiting guidelines. However, updating the same object in such rapid succession could result in save errors that negatively impact both your integration as well as user experience within the Smartsheet app. To avoid this scenario, design your integration such that API requests are never executed with rapid-fire succession against the same Smartsheet object. For maximum efficiency, consider batching up changes and submitting them in a single request using a bulk operation (for example, Update Rows or Add Columns.

Execute Requests Serially

Executing multiple API requests in parallel to update a specific Smartsheet object results in reduced performance and often results in errors due to save collisions. To avoid this scenario, design your integration such that API requests to update a specific Smartsheet object are always executed serially (that is, execute one request at time, not beginning the next request until the previous request has completed).

NOTE: Attempts to perform multiple concurrent updates to a sheet may result in error code 4004.

Use the Smartsheet SDKs

The SDKs provide default backoff and retry to accommodate rate limiting responses from the API. Note that the default maximum retry duration is typically 30 seconds. You may wish to increase this if your application is making many API calls in quick succession. For specific instructions per language, see the Readme for the respective SDK.