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 user 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 have 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.

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. It is very important to be frugal with the API.

Sync Flowchart Folder Sync Flowchart Context Sync Flowchart Goal Sync Flowchart Location Sync Flowchart Task Sync Flowchart Notebook Sync Flowchart

Rate Limiting

Each user is allowed to request 10 tokens per hour via the "/account/token.php" API call. Any further token requests will be blocked. A Token is valid for 4 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 250 requests per 60 minute time period. If you cache your data properly, this should be more than enough for any application.

If you make more than 250 requests in a 60 minute period, any further requests will generate an error message until the request/hour drops below 250.

Toodledo reserves the right to imposed stricter rate limiting on a per-application basis if we determined that a poorly designed application is using a disproportionate amount of our resources.