Question 1

What can I build with the Intervals API?

Accepted Answer

Surface the races, clubs, and group runs you host on Intervals on your own site — your location and event pages — kept current automatically. For a business with physical locations, that's real local-SEO value: a live, recurring schedule on each location page is exactly the fresh, location-tagged content that ranks for 'run club near me' and gives regulars a reason to keep checking back. You can also create events and register participants programmatically.

Question 2

How do I authenticate?

Accepted Answer

Every request uses a Bearer API key scoped to your organization, sent in the Authorization header. Create a key in the manage portal under Settings → API. All requests go to https://api.intervals.run.

Question 3

Which plans include API access?

Accepted Answer

API access is included on the Elite and Enterprise plans. If an organization's plan doesn't include it, requests return a 403 with code API_ACCESS_REQUIRED until you upgrade.

Question 4

What are the rate limits?

Accepted Answer

Elite allows 300 requests per minute (burst 100); Enterprise allows 1,000 requests per minute (burst 300). Every response reports your current limit, remaining, and reset via RateLimit-* headers, and a 429 adds a Retry-After header telling you how long to wait.

Question 5

Is the API versioned?

Accepted Answer

Versioning is header-based via the Intervals-Version header. The API is currently unversioned, so you can omit it; sending an unrecognized version returns a 400 so a typo never silently changes behavior.

Question 6

How does pagination work?

Accepted Answer

List endpoints use forward-only cursor pagination. Read the opaque cursor from a response and pass it back as the after query parameter to fetch the next page. The limit parameter ranges from 1 to 100 and defaults to 50.

Question 7

Are write requests safe to retry?

Accepted Answer

Yes. POST endpoints require an Idempotency-Key header — resending the same key replays the original response instead of creating a duplicate, so network retries and timeouts are safe.

Question 8

How are errors returned?

Accepted Answer

Errors use a consistent JSON envelope with a stable, machine-readable code: { "error": { "code", "message" } }. Branch on error.code rather than the message text. Every response also carries an X-Request-Id you can quote to support.

Intervals API

Endpoints

Frequently asked questions

Ready to build?