Intervals Developers
API Reference
Sign inGet API key
IntroductionAuthenticationErrorsPaginationRate LimitsIdempotency

Endpoints

GETYour organizationGETAll eventsGETRetrieve an eventPOSTCreate an eventGETAll registrationsPOSTRegister a participantGETAll recurrencesGETAll groupsGETRetrieve a groupGETEvents in a group
Changelog
Sign inGet API key

API Reference

Pagination

List endpoints use cursor-based pagination for stable navigation, even as data changes between requests.

Paginated responses include:

dataThe list of returned items.
hasMoreWhether there are more items available.

Navigate through results using the following query parameters:

limitNumber of items to return per page (1–100, default 50).
afterCursor to get the next page of results.
beforeCursor to get the previous page of results.

Use the _id of objects as the cursor for pagination. The cursor itself is excluded from the results. You can use either after or before, not both.

Response format

{
  "data": [
    { "_id": "abc123", ... },
    { "_id": "def456", ... }
  ],
  "hasMore": true
}

Forward pagination

# First page
curl -H "Authorization: Bearer INTERVALS_PARTNER_API_KEY" \
  "https://api.intervals.run/events?limit=20"

# Next page (use _id of last item from previous response)
curl -H "Authorization: Bearer INTERVALS_PARTNER_API_KEY" \
  "https://api.intervals.run/events?limit=20&after=def456"
async function fetchAllEvents(apiKey) {
  const events = [];
  let after = undefined;

  while (true) {
    const params = new URLSearchParams({ limit: "50" });
    if (after) params.set("after", after);

    const res = await fetch(
      `https://api.intervals.run/events?${params}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    const page = await res.json();

    events.push(...page.data);

    if (!page.hasMore) break;
    after = page.data.at(-1)._id;
  }

  return events;
}

Backward pagination

# Previous page (use _id of first item from current page)
curl -H "Authorization: Bearer INTERVALS_PARTNER_API_KEY" \
  "https://api.intervals.run/events?limit=20&before=abc123"

Supported endpoints

  • List Events
  • List Series
  • List Registrations

Best practices

  • Always check hasMore before requesting additional pages
  • Choose a limit that balances performance and usability — smaller pages for real-time UIs, larger for bulk processing
  • Be mindful of rate limits when paginating through large datasets

Error handling

Pagination requests may return the following validation errors:

ErrorDescription
VALIDATION_ERRORInvalid cursor format or limit out of range (1–100)
VALIDATION_ERRORBoth before and after provided
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "errors": {
      "limit": ["Number must be less than or equal to 100"]
    }
  }
}
ErrorsRate Limits