Event Feeds

Aggregate and monitor events from websites, sitemaps, and social media with structured event data including dates, times, and locations.

Getting Started: Event feeds and sources are managed by Helix for optimal performance. Contact Helix support to set up feeds and configure sources for your use case.

Overview

Event feeds collect events from multiple sources into a single, organized stream. Each feed continuously monitors its sources for new events, automatically extracting structured data including titles, descriptions, dates, times, and geographic locations.

Key benefits:

Automatic discovery: New events are detected and processed without manual intervention
Rich event data: Structured information with dates, times, locations, and occurrences
Flexible retrieval: Access via API polling or webhooks
Historical backfill: Automatically includes recent events when adding sources

Quick Example

Once your feed is configured by Helix support, retrieving events is straightforward:

# Retrieve events from your feed
curl "https://api.feeds.onhelix.ai/feeds/events/{feedId}/items?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

See the Quickstart Guide for a complete walkthrough.

How It Works

When Helix sets up your event feed:

Source configuration: Helix configures sources (websites, sitemaps, social accounts) for your feed
Automatic backfill: Recent events from the past 14 days are automatically added to your feed
Continuous monitoring: Sources are continuously monitored for new events
Event extraction: Events are automatically extracted with dates, times, and locations

Event Feed Items

Each item in your feed has a flattened, source-agnostic shape. Optional fields are omitted (not nulled) when missing; arrays are always present (empty when no data).

Field	Description
`id`	Stable feed-item identifier (per-feed). Use this for feedback and per-feed dedup.
`eventId`	Underlying event identifier. Same event in two feeds yields different `id` but same `eventId`.
`title`	Event title
`description`	Event description
`addedToFeedAt`	When the event was added to this feed
`publishedAt`	Original publish time on the source platform (omitted when unknown)
`occurrence`	Occurrence summary — `nextOccurrence`, `occurrencesInRange[]`, `totalOccurrences`, `upcomingOccurrences`
`time`	Time-display info (omitted when not derivable)
`location`	Location info (omitted when not available)
`primaryImage`	Hero image URL (omitted when not available)
`supportingImages`	Array — empty when no supporting images
`primaryUrl`	Primary external URL for the event (omitted when not available)
`urls`	Array of associated URLs (empty when none)
`geoLocations`	Array of geo associations (empty when none)
`source`	Per-platform detail block, present only when requested via `?include=source`

Example event feed item:

{
  "id": "660e8400-e29b-41d4-a716-446655440003",
  "eventId": "880e8400-e29b-41d4-a716-446655440004",
  "title": "Summer Music Festival",
  "description": "Three-day outdoor music festival featuring local and national artists...",
  "addedToFeedAt": "2024-01-15T12:00:00.000Z",
  "occurrence": {
    "nextOccurrence": {
      "id": "occ_jkl012",
      "instanceId": "instance_ghi789",
      "startDateTime": "2024-07-12T18:00:00.000Z",
      "endDateTime": "2024-07-12T23:00:00.000Z",
      "status": "scheduled"
    },
    "occurrencesInRange": [
      {
        "id": "occ_jkl012",
        "instanceId": "instance_ghi789",
        "startDateTime": "2024-07-12T18:00:00.000Z",
        "endDateTime": "2024-07-12T23:00:00.000Z",
        "status": "scheduled"
      },
      {
        "id": "occ_mno345",
        "instanceId": "instance_ghi789",
        "startDateTime": "2024-07-13T18:00:00.000Z",
        "endDateTime": "2024-07-13T23:00:00.000Z",
        "status": "scheduled"
      }
    ],
    "totalOccurrences": 2,
    "upcomingOccurrences": 2
  },
  "supportingImages": [],
  "urls": [],
  "geoLocations": [
    {
      "id": "geo_pqr678",
      "description": "City Park Amphitheater, Portland, OR",
      "relationType": "LOCATION",
      "score": 0.95,
      "instanceId": "instance_ghi789"
    }
  ]
}

See the API reference for the full per-platform shape and the opt-in ?include=source block.

Use Cases

Event Discovery Platform

Build comprehensive event listings by having Helix configure a feed that aggregates events from multiple venue sources. Once configured, you can retrieve all city events through a single API endpoint.

Community Calendar

Aggregate local community events by fetching events from your feed, filtering for upcoming occurrences, and sorting by start date.

Tourism and Travel

Aggregate events for travel planning by fetching events in a destination and grouping them by date for easy itinerary creation.

Venue Management

Monitor competitors or industry events by having Helix configure feeds that track competitor venue schedules, allowing you to stay informed about industry trends and competitor activities.

Feed Management

Enabling and Disabling Feeds

Temporarily pause all monitoring without deleting the feed:

# Disable a feed
curl -X PATCH https://api.feeds.onhelix.ai/feeds/events/{feedId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"enabled": false}'

# Re-enable later
curl -X PATCH https://api.feeds.onhelix.ai/feeds/events/{feedId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"enabled": true}'

When disabled, the feed stops monitoring for new events. Re-enabling resumes monitoring but does not backfill events published while disabled.

Webhooks

Receive notifications when new events are published.

Available events:

event.item_added - Triggered when a new event is published and available in your feed

When webhooks send:

Webhooks fire immediately when:

A new event is discovered from any of your sources
Event data is extracted including dates, times, and locations
The event is successfully added to your feed

What you receive:

Each webhook includes complete event details:

Event title and description
Start and end times with timezone information
Location details (venue, city, country, coordinates)
Event category (sports, entertainment, business, etc.)
Participants and metadata

Example webhook payload:

{
  "event": "event.item_added",
  "timestamp": "2025-11-08T12:34:56.789Z",
  "data": {
    "event_id": "evt_1234567890",
    "title": "Summer Music Festival",
    "description": "Three-day outdoor music festival...",
    "start_time": "2025-07-12T18:00:00.000Z",
    "end_time": "2025-07-12T23:00:00.000Z",
    "location": {
      "name": "City Park Amphitheater",
      "city": "Portland",
      "country": "US"
    }
  }
}

See the Event Webhooks documentation for complete payload details, security verification, and setup instructions.

Next Steps

Quickstart Guide: Start using event feeds in 5 minutes
API Reference: Complete endpoint documentation
Webhooks: Webhook notifications for new events
Authentication: API key management and best practices

Need Help?

To set up event feeds, configure sources, or request changes to your existing feeds:

Contact Helix Support - Our team will work with you to configure feeds that meet your specific requirements, including:

Setting up new event feeds
Configuring sources (websites, sitemaps, social media)
Adding or removing sources from existing feeds
Adjusting feed settings and monitoring parameters

Helix manages feed configuration to ensure optimal performance, reliability, and data quality.

Event Feeds

Overview​

Quick Example​

How It Works​

Event Feed Items​

Use Cases​

Event Discovery Platform​

Community Calendar​

Tourism and Travel​

Venue Management​

Feed Management​

Enabling and Disabling Feeds​

Webhooks​

Next Steps​

Need Help?​