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.
Supported Source Types
Event feeds reference sources by ID rather than defining them inline (see Source Reference in Event Feeds Concepts). Helix supports the following source types when configuring sources for your feed:
Website Sources
Monitor an entire domain for event pages.
Use when:
- You want to track all events published by a venue or organization
- The site has clear, dedicated event pages
- You don't need to limit monitoring to a specific page or section
Helix crawls the domain to discover event pages and extracts structured event data (dates, times, locations) as new pages are published.
Sitemap Sources
Track a specific XML sitemap for event URLs.
Use when:
- The site publishes a sitemap listing event pages
- You want faster, more targeted event discovery than a full-site crawl
Helix monitors the sitemap for new URLs and extracts event data from the pages it references.
Index Page Sources
Watch a calendar or events listing page.
Use when:
- The site organizes events on a dedicated calendar or listing page
- You want focused monitoring of that page instead of the whole domain
Helix monitors the index page for links to individual event pages and processes new events as they're added to the listing.
Instagram Sources
Monitor an Instagram account for event announcements.
Helix watches the account's posts and reels for event announcements and extracts structured event data (dates, times, locations) when found.
Facebook Sources
Track events from Facebook pages.
Helix monitors the Facebook page's published events and extracts structured event data as new events are posted.
To add or change sources on your feed, contact Helix support.
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.
Event Delivery
Get notified in real time when new events are published, instead of polling for changes.
Available event type:
event.item.added- a new event was added to your feed
Having an event feed does not, by itself, cause anything to be delivered. Event Delivery only sends an event to a destination that has a subscription matching this feed — you register the destination once, then subscribe it to the feeds and event types you care about. See Event Delivery: Two objects, not one for details.
See the Event Delivery overview to set up a
destination and subscription, and the
event.item.added reference
for the full payload schema and an example.
Next Steps
- Quickstart Guide: Start using event feeds in 5 minutes
- API Reference: Complete endpoint documentation
- Event Delivery: Configure destinations and subscriptions to receive events in real time
- 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.