Toggl Track API 限速 & 低速模式

Toggl Track 于 2025-09-05 开始限制 API 的使用，免费用户只能以 30 次/小时的速率请求 API。超出限制后年轮将无法与 Toggl 进行同步，需要等待 1 小时后限额重置才能继续同步。因此，年轮提供了 API 使用情况的统计，以及提供低速模式，避免用户超出使用限制，影响数据同步效率。

具体的 toggl API 使用限制，请参考 toggl 官方说明。

定时同步

年轮会定时向 toggl 查询 Project / Tag / TimeEntry 的变更，以实现同步。在低速模式下，年轮的查询间隔会延长，以下是低速模式下的时间间隔：

Project / Tag：60 分钟
TimeEntry：5 分钟

在非低速模式下，年轮的同步时间间隔为：

Project / Tag： 60 秒
TimeEntry：5 秒

年轮在 2025-09-05 后将开始自动开启 toggl API 的低速模式，避免用户超出使用限制，影响数据同步效率。若你的帐号不受限速影响，或 toggl 官方移除了 API 的限速，你也可以手动关闭限速开关，然后重启年轮 App，即可恢复到非低速模式。

API 请求记录统计

年轮内的 toggl API 请求记录仅统计当前设备的请求，不包括其他设备的年轮，以及你其他使用 toggl API 的 App 或程序（例如其他登陆了相同 toggl 帐号的第三方 App）。具体是否触发 toggl API 使用限制，请以实际情况为准，可能会出现年轮 App 内请求记录未达到限制数量，但实际请求已触发限制的情况。

🌰

举例说明

这种情况通常是其他设备或 App 对 toggl API 存在调用，年轮无法统计，而调用的总和超出了 toggl 的 API 使用数量限制。

触发 toggl API 使用限制后，年轮在 toggl API 用量恢复之前无法通过 API 读取或写入数据到 toggl。你无需进行任何操作，年轮会自动在 API 用量恢复后，自动恢复同步。

低速模式

年轮的 toggl API 低速模式会对以下部分产生影响：

toggl 定时同步的间隔时间
“与 Toggl 对比数据” 工具在低速模式仅会拉取 toggl 最近3个月内的 Time Entry，避免过多的查询请求立刻触发 API 使用限制。

开启 App 时同步 Time Entry

为了保证 toggl 同步的使用体验，年轮在 App 切换到前台时，会自动触发一次 Time Entry 的同步，保证每次开启 App 时，都能自动获取到最新的 Time Entry 数据。若你发现你的 API 用量过高，你可以在年轮的 toggl 设置页中关闭这个功能，以减少 API 的用量。

手动开启低速模式

2025-09-05 之前，正式版本的低速模式开关默认关闭，而 TestFlight 版本默认开启低速模式。你可手动切换低速模式的开关。
2025-09-05 后，低速模式的开关将自动隐藏，并默认开启低速模式。在这之后你可使用“暂停 API 低速模式” 开关，手动禁用低速模式。