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) on the venue's clock — see `timezone`.

organizationIdstringrequired

Owning organization ID

startTimestring

Start time (HH:MM) on the venue's clock — see `timezone`.

timezonestring

The venue's IANA timezone (e.g. America/Los_Angeles): the clock every date and time on this event is read on. Absent while the venue's location is not known; then dates and times are the venue's own, with no offset.

startsAtstring

The start as an ISO-8601 instant with the venue's offset (e.g. 2026-04-18T07:00:00-07:00). Present when `startTime` and `timezone` are both known.

addressobject

Event location

latnumber

lngnumber

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 on the venue's clock at the time of the request: past | in_progress | future. While `timezone` is not known the dates are read Anywhere on Earth (UTC−12), so a day lasts until it has ended everywhere.

Available options: past,in_progress,future

endDatestring

End date for multi-day events (YYYY-MM-DD) on the venue's clock

endTimestring

End time (HH:MM) on the venue's clock

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) on the venue's clock — see the event's `timezone`.

startTimestring

Start time (HH:MM) on the venue's clock — see the event's `timezone`.

startsAtstring

The run's start as an ISO-8601 instant with the venue's offset. Present when `startTime` and the event's `timezone` are both known.

eventStatusenum<string>

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

Available options: scheduled,cancelled,postponed,rescheduled

registrationUrlstring

Registration URL

registrationobjectrequired

Derived registration state.

maxParticipantsnumber

Capacity — runners, or teams on a run with relay.

registrationCountnumber

Runners registered — pair with maxParticipants for entries left. A run with relay sells team entries instead, so nothing counts here; read entryCount there.

isVirtualboolean

Whether this is a virtual run

isRelayboolean

Whether this is a relay

isWalkingboolean

Whether this is a walking event

isWheelchairboolean

Whether this is a wheelchair division: its own start, field and results

relayobject

Team configuration, present only on runs where you enter a team rather than an individual. Detect those runs by its presence — isRelay can be set on a run that carries none.

entryCountnumber

Teams registered — pair with maxParticipants for entries left on a run with relay.

{
  "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",
        "maxParticipants": 400,
        "registrationCount": 187,
        "registration": {
          "phase": "open",
          "isOpen": true,
          "closesAt": "2025-06-13T23:59:59-04:00"
        }
      },
      {
        "id": "r41ghi234jkl567",
        "eventId": "e72tuv901wxy234",
        "distanceMeters": 5000,
        "distanceStandard": "5K",
        "distanceLabel": "5K Relay",
        "date": "2025-06-14",
        "startTime": "08:30",
        "eventStatus": "scheduled",
        "maxParticipants": 150,
        "isRelay": true,
        "relay": {
          "legs": [
            {
              "label": "Leg 1",
              "atMeters": 0
            },
            {
              "label": "Leg 2",
              "atMeters": 2500
            }
          ],
          "teamSize": 2
        },
        "entryCount": 104,
        "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",
        "maxParticipants": 400,
        "registrationCount": 187,
        "registration": {
          "phase": "open",
          "isOpen": true,
          "closesAt": "2025-06-13T23:59:59-04:00"
        }
      },
      {
        "id": "r41ghi234jkl567",
        "eventId": "e72tuv901wxy234",
        "distanceMeters": 5000,
        "distanceStandard": "5K",
        "distanceLabel": "5K Relay",
        "date": "2025-06-14",
        "startTime": "08:30",
        "eventStatus": "scheduled",
        "maxParticipants": 150,
        "isRelay": true,
        "relay": {
          "legs": [
            {
              "label": "Leg 1",
              "atMeters": 0
            },
            {
              "label": "Leg 2",
              "atMeters": 2500
            }
          ],
          "teamSize": 2
        },
        "entryCount": 104,
        "registration": {
          "phase": "open",
          "isOpen": true,
          "closesAt": "2025-06-13T23:59:59-04:00"
        }
      }
    ]
  }
}