Terra · Rate Limits

Terra Api Rate Limits

Terra does not throttle the data-read endpoints by a conventional requests-per-second cap. Instead it meters a per-user "day budget": the cost of a data request equals the number of days it spans (end_date - start_date), and requests without date parameters count as one day. A single request may span at most 1,825 days (5 years), and a user may spend at most 6,000 days in a rolling one-hour bucket. Throttled calls return HTTP 429 with X-Terra-RateLimit-* headers indicating which rule fired and when the bucket resets. Webhook delivery - Terra's primary data-streaming mechanism - is not subject to these inbound read limits.

Terra Api Rate Limits is the machine-readable rate-limit profile for Terra on the APIs.io network, conforming to the API Commons Rate Limits specification.

It captures 3 rate-limit definitions, measuring days and events.

The profile also includes 4 backoff/retry policies defined and response codes documented for throttled.

Tagged areas include Wearables, Health Data, Fitness, Rate Limiting, and Quotas.

3 Limits Throttle: 429
WearablesHealth DataFitnessRate LimitingQuotas

Limits

Per-Request Day Span request
days
1825
A single data-read request may span at most 1,825 days (5 years). Rule r1.
Cumulative Hourly Day Budget user
days
6000
A user may spend at most 6,000 days across data-read requests in a rolling one-hour bucket; request cost = end_date - start_date in days (undated requests count as 1). Rule r2.
Webhook Delivery account
events
not rate-limited
Outbound webhook streaming of data and lifecycle events is not subject to the inbound read limits.

Policies

Day-Budget Metering
Read-endpoint cost is measured in days requested, not request count, so a few wide historical pulls can exhaust the budget faster than many narrow ones. Chunk large backfills to stay within the 6,000-day hourly bucket.
Retry-After
On an r2 (cumulative) violation the 429 includes a Retry-After header with the seconds until the hourly bucket resets; clients should back off until then rather than retrying immediately.
Budget Visibility
Successful responses expose X-Terra-RateLimit-Limit, -Remaining, and -Reset-After so clients can pace historical requests against the remaining day budget.
Prefer Webhooks
Because webhook delivery is not rate-limited, prefer to_webhook=true and react to pushed events rather than polling the read endpoints.

Sources