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 more items are available.

cursorOpaque pointer to the next page, present only when hasMore is true. Pass it back as after.

Control each request with these query parameters:

limitNumber of items to return per page (1–100, default 50).

afterCursor from a previous response's cursor field; returns the next page.

Pagination is forward-only. Read the cursor from each response and pass it as after to get the next page — treat cursors as opaque; don't construct or parse them.

Response format

{
  "data": [
    { "id": "e72tuv901wxy234", "name": "Saturday 5K" },
    { "id": "e83ghi012jkl345", "name": "Sunday 10K" }
  ],
  "hasMore": true,
  "cursor": "kf82hs0dk3nfy1..."
}

Fetching every page

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

# Next page — pass the previous response's `cursor` as `after`
curl -H "Authorization: Bearer INTERVALS_PARTNER_API_KEY" \
  "https://api.intervals.run/events?limit=20&after=kf82hs0dk3nfy1..."

async function fetchAllEvents(apiKey) {
  const events = [];
  let after;

  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.cursor;
  }

  return events;
}

Supported endpoints

Best practices

Always check hasMore before requesting another page
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 error:

Error	Description
`VALIDATION_ERROR`	The `limit` is out of range (must be 1–100).

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "errors": {
      "limit": ["Number must be less than or equal to 100"]
    }
  }
}

Fetching every page

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

# Next page — pass the previous response's `cursor` as `after`
curl -H "Authorization: Bearer INTERVALS_PARTNER_API_KEY" \
  "https://api.intervals.run/events?limit=20&after=kf82hs0dk3nfy1..."

async function fetchAllEvents(apiKey) {
  const events = [];
  let after;

  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.cursor;
  }

  return events;
}

Error handling

Pagination requests may return the following validation error:

Error	Description
`VALIDATION_ERROR`	The `limit` is out of range (must be 1–100).

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "errors": {
      "limit": ["Number must be less than or equal to 100"]
    }
  }
}