Overview

The Focus API provides programmatic access to Toggl Focus, enabling you to manage tasks, projects, time blocks, and other Focus-specific resources.

The documentation is split between a friendly Getting Started section and an API Reference section with a detailed listing of available endpoints.

The API Format

The API accepts only JSON requests. Please make sure you're setting Content-Type: application/json in your request header. Each request returns a JSON-encoded body. The result of each action is communicated via standard HTTP response codes.

Times and dates use the ISO 8601 standard, more specifically a subset described in RFC 3339. Times and dates are stored in UTC (GMT). On return, the data is set into the appropriate timezone according to the setting in the user profile.

API Quota

To avoid overloading our systems and enable fair use of our API, we enforce a per-organization hourly request quota. This is applied per user per organization. Upon reaching the limit, requests will receive an HTTP 402 (Payment Required) response and the client must wait before making the next request.

Why 402 instead of 429?

Focus uses 402 because quota limits are tied to the organization's subscription plan. Exceeding the quota signals that the current plan's allocation has been consumed — upgrading the plan increases the limit. This is distinct from a generic rate limit (429), which typically implies a transient throttle unrelated to billing.

To help clients identify their consumption, we provide the following response headers:

• X-Toggl-Quota-Remaining: how many requests you have left in the current window.
• X-Toggl-Quota-Resets-In: how many seconds until the current window resets.

Quotas are determined by the organization's subscription plan:

• Free: 30 requests per hour, per user, per organization
• Starter: 240 requests per hour, per user, per organization
• Premium: 600 requests per hour, per user, per organization

Higher, custom quotas are available on Enterprise plans.

General principles

• In case of an update request, send only the fields that have changed
• Fetch only the data you need

Generic responses

We use standard HTTP status codes:

• 4xx errors: don't retry with the same payload, inspect the response body for details
• 5xx errors: add a random delay before retrying
• 402 (Payment Required): you have exceeded your hourly API quota — wait until the window resets, or upgrade your plan for a higher limit