What can I build with this endpoint?

A full event page you embed on your own site: map the location, count down to the date, list the distance options, and link straight to signup.

What are the lat and lng fields useful for?

Mapping and proximity. Drop every event on a map, or sort and filter by distance from a runner's location to power a 'races near me' experience — the coordinates are already resolved, so there's no geocoding on your end.

What are cardImageUrl and coverImageUrl for?

They're hosted, ready-to-render images for each event or collection — use cardImageUrl in a grid and coverImageUrl as a page hero, so you don't have to store or generate artwork yourself.

What is the registrationUrl field for?

It's the canonical link to register for the event — point your own 'Register' button at it so signups still flow through Intervals.

How do I tell upcoming events from past ones?

Read temporalStatus — it resolves to past, in_progress, or future from the event's dates (timezone-safe), so you can badge live events, hide finished ones, or default your list to what's next.

Endpoints

Retrieve an event

Retrieve a single event along with its associated runs (distance variants), including event details and an array of event runs.

GET/events/:id

curl -H "Authorization: Bearer INTERVALS_PARTNER_API_KEY" \
  https://api.intervals.run/events/e72tuv901wxy234

Path Parameters

idstringrequired

The event ID

Authorization

read:events

Response — Event

idstringrequired

Event ID

namestringrequired

Event name

slugstringrequired

URL slug

typeenum<string>required

Event type

Available options: race,runClub,timeTrial,other

datestringrequired

Event date (YYYY-MM-DD)

organizationIdstringrequired

Owning organization ID

startTimestring

Start time (HH:MM)

addressobject

Event location

latnumber

Latitude

lngnumber

Longitude

descriptionstring

Event description

websiteUrlstring

Event website URL

cardImageUrlstring

Card image URL (grid/list thumbnails).

coverImageUrlstring

Cover/hero image URL (event pages).

registrationUrlstring

Registration page URL

temporalStatusenum<string>required

Derived from the event's dates: past | in_progress | future.

Available options: past,in_progress,future

endDatestring

End date for multi-day events (YYYY-MM-DD)

endTimestring

End time (HH:MM)

Response — Run

idstringrequired

Event run ID

eventIdstringrequired

Parent event ID

distanceMetersnumberrequired

Distance in meters

distanceStandardenum<string>required

Standard distance label

Available options: 5K,10K,15K,Half Marathon,Marathon,50K,50M,100K,100M,Ultra,Other

distanceLabelstringrequired

Display label for the distance

datestringrequired

Run date (YYYY-MM-DD)

startTimestring

Start time (HH:MM)

eventStatusenum<string>

Organizer-set lifecycle: scheduled | cancelled | postponed | rescheduled.

Available options: scheduled,cancelled,postponed,rescheduled

registrationUrlstring

Registration URL

registrationobjectrequired

Derived registration state.

maxParticipantsnumber

Maximum participants (capacity).

registrationCountnumber

Current registrations — pair with maxParticipants for spots left.

isVirtualboolean

Whether this is a virtual run

isRelayboolean

Whether this is a relay

isWalkingboolean

Whether this is a walking event

{
  "data": {
    "event": {
      "id": "e72tuv901wxy234",
      "name": "Lakefront 5K - June 14",
      "slug": "lakefront-5k-june-14",
      "type": "race",
      "date": "2025-06-14",
      "organizationId": "k57abc123def456",
      "startTime": "08:00",
      "description": "Weekly lakefront 5K race along the scenic shore path.",
      "websiteUrl": "https://northshorerace.com/lakefront-5k",
      "temporalStatus": "future"
    },
    "runs": [
      {
        "id": "r41abc567def890",
        "eventId": "e72tuv901wxy234",
        "distanceMeters": 5000,
        "distanceStandard": "5K",
        "distanceLabel": "5K",
        "date": "2025-06-14",
        "startTime": "08:00",
        "eventStatus": "scheduled",
        "registration": {
          "phase": "open",
          "isOpen": true,
          "closesAt": "2025-06-13T23:59:59-04:00"
        }
      }
    ]
  }
}

What you can build

Request

curl -H "Authorization: Bearer INTERVALS_PARTNER_API_KEY" \
  https://api.intervals.run/events/e72tuv901wxy234

Response

{
  "data": {
    "event": {
      "id": "e72tuv901wxy234",
      "name": "Lakefront 5K - June 14",
      "slug": "lakefront-5k-june-14",
      "type": "race",
      "date": "2025-06-14",
      "organizationId": "k57abc123def456",
      "startTime": "08:00",
      "description": "Weekly lakefront 5K race along the scenic shore path.",
      "websiteUrl": "https://northshorerace.com/lakefront-5k",
      "temporalStatus": "future"
    },
    "runs": [
      {
        "id": "r41abc567def890",
        "eventId": "e72tuv901wxy234",
        "distanceMeters": 5000,
        "distanceStandard": "5K",
        "distanceLabel": "5K",
        "date": "2025-06-14",
        "startTime": "08:00",
        "eventStatus": "scheduled",
        "registration": {
          "phase": "open",
          "isOpen": true,
          "closesAt": "2025-06-13T23:59:59-04:00"
        }
      }
    ]
  }
}

Endpoints

Retrieve an event

Retrieve a single event along with its associated runs (distance variants), including event details and an array of event runs.

GET/events/:id

curl -H "Authorization: Bearer INTERVALS_PARTNER_API_KEY" \
  https://api.intervals.run/events/e72tuv901wxy234

Path Parameters

idstringrequired

The event ID

Authorization

read:events

Response — Event

idstringrequired

Event ID

namestringrequired

Event name

slugstringrequired

URL slug

typeenum<string>required

Event type

Available options: race,runClub,timeTrial,other

datestringrequired

Event date (YYYY-MM-DD)

organizationIdstringrequired

Owning organization ID

startTimestring

Start time (HH:MM)

addressobject

Event location

latnumber

Latitude

lngnumber

Longitude

descriptionstring

Event description

websiteUrlstring

Event website URL

cardImageUrlstring

Card image URL (grid/list thumbnails).

coverImageUrlstring

Cover/hero image URL (event pages).

registrationUrlstring

Registration page URL

temporalStatusenum<string>required

Derived from the event's dates: past | in_progress | future.

Available options: past,in_progress,future

endDatestring

End date for multi-day events (YYYY-MM-DD)

endTimestring

End time (HH:MM)

Response — Run

idstringrequired

Event run ID

eventIdstringrequired

Parent event ID

distanceMetersnumberrequired

Distance in meters

distanceStandardenum<string>required

Standard distance label

Available options: 5K,10K,15K,Half Marathon,Marathon,50K,50M,100K,100M,Ultra,Other

distanceLabelstringrequired

Display label for the distance

datestringrequired

Run date (YYYY-MM-DD)

startTimestring

Start time (HH:MM)

eventStatusenum<string>

Organizer-set lifecycle: scheduled | cancelled | postponed | rescheduled.

Available options: scheduled,cancelled,postponed,rescheduled

registrationUrlstring

Registration URL

registrationobjectrequired

Derived registration state.

maxParticipantsnumber

Maximum participants (capacity).

registrationCountnumber

Current registrations — pair with maxParticipants for spots left.

isVirtualboolean

Whether this is a virtual run

isRelayboolean

Whether this is a relay

isWalkingboolean

Whether this is a walking event

{
  "data": {
    "event": {
      "id": "e72tuv901wxy234",
      "name": "Lakefront 5K - June 14",
      "slug": "lakefront-5k-june-14",
      "type": "race",
      "date": "2025-06-14",
      "organizationId": "k57abc123def456",
      "startTime": "08:00",
      "description": "Weekly lakefront 5K race along the scenic shore path.",
      "websiteUrl": "https://northshorerace.com/lakefront-5k",
      "temporalStatus": "future"
    },
    "runs": [
      {
        "id": "r41abc567def890",
        "eventId": "e72tuv901wxy234",
        "distanceMeters": 5000,
        "distanceStandard": "5K",
        "distanceLabel": "5K",
        "date": "2025-06-14",
        "startTime": "08:00",
        "eventStatus": "scheduled",
        "registration": {
          "phase": "open",
          "isOpen": true,
          "closesAt": "2025-06-13T23:59:59-04:00"
        }
      }
    ]
  }
}

What you can build

Request

curl -H "Authorization: Bearer INTERVALS_PARTNER_API_KEY" \
  https://api.intervals.run/events/e72tuv901wxy234

Response

{
  "data": {
    "event": {
      "id": "e72tuv901wxy234",
      "name": "Lakefront 5K - June 14",
      "slug": "lakefront-5k-june-14",
      "type": "race",
      "date": "2025-06-14",
      "organizationId": "k57abc123def456",
      "startTime": "08:00",
      "description": "Weekly lakefront 5K race along the scenic shore path.",
      "websiteUrl": "https://northshorerace.com/lakefront-5k",
      "temporalStatus": "future"
    },
    "runs": [
      {
        "id": "r41abc567def890",
        "eventId": "e72tuv901wxy234",
        "distanceMeters": 5000,
        "distanceStandard": "5K",
        "distanceLabel": "5K",
        "date": "2025-06-14",
        "startTime": "08:00",
        "eventStatus": "scheduled",
        "registration": {
          "phase": "open",
          "isOpen": true,
          "closesAt": "2025-06-13T23:59:59-04:00"
        }
      }
    ]
  }
}