Developer's API Documentation : Sync & Rate Limiting

Scheduled Syncing

If your application will have automatic background syncing, it should not sync more frequently than once an hour. For the vast majority of applications this is frequent enough. Your users can always sync manually if they need to. Applications that sync too frequently may be restricted.

If your application will be syncing on a schedule, you should avoid having it automatically sync at a particular time of the day (for example: on the hour, at midnight, etc). This will cause our servers to have spikes in traffic at these particular times, which will cause degraded performance for your customers. A better way to do this is to have your application pick a random time offset. For example, if you sync once an hour, instead of having everyone sync at 4:00, have each installation of the app pick a random offset into the hour, so that some people sync at 4:13, some at 4:28, etc.

Rate Limiting

Each user is allowed to request 10 access tokens per hour via the "/account/token.php" API call. Any further token requests will be blocked. An access token is valid for 2 hours, so it should never be necessary to get this many tokens. You should cache and reuse a token until it expires.

In addition, each authenticated user is allowed to make 100 API calls per access token. This means that you can make 1,000 API calls per hour for each user. If you cache your data properly, this should be more than enough for any application to sync.

If you make more than 100 API calls with a token, any further requests will generate an error message until you refresh the token.

Toodledo reserves the right to impose stricter rate limiting on a per-application basis if we determined that a poorly designed application is using a disproportionate amount of our resources. We can also whitelist apps for higher limits if necessary. Please contact us if you need this.

Synchronization

If you are building an application that intends to synchronize with Toodledo, please read this section for suggestions about how to do this efficiently.

Each time you attempt a synchronization, your application should use the "/account/get.php" API call. This will return several timestamps which you can use to determine if any further action is needed.

For example, the "lastedit_task" timestamp will indicate the last time that a task was added or edited. If this value has changed since the last time you checked, you can call "/tasks/get.php" and set the "modafter" parameter to fetch the tasks that have changed. You can do a similar timestamp comparison to determine if folders, contexts, goals, locations or notebooks have changed since your last sync.

In many cases, nothing will have changed and the only thing you need to do is call "account/get.php" to determine this before you terminate sync. It is very important to be frugal with the API.