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 includes rich structured data:

Field	Description
`id`	Unique identifier for the feed item
`eventFeedId`	Reference to the parent feed
`eventId`	Reference to the underlying event
`event.title`	Event name/title
`event.description`	Event description
`event.instances`	Event instances (when/where)
`event.instances[].occurrences`	Specific dates and times
`event.instances[].eventGeoLocations`	Geographic locations
`createdAt`	When the item was added to your feed
`updatedAt`	Last time the item was modified

Example event feed item:

{
  "id": "660e8400-e29b-41d4-a716-446655440003",
  "eventFeedId": "550e8400-e29b-41d4-a716-446655440000",
  "eventId": "880e8400-e29b-41d4-a716-446655440004",
  "event": {
    "id": "880e8400-e29b-41d4-a716-446655440004",
    "title": "Summer Music Festival",
    "description": "Three-day outdoor music festival featuring local and national artists...",
    "instances": [
      {
        "id": "instance_ghi789",
        "eventId": "880e8400-e29b-41d4-a716-446655440004",
        "occurrences": [
          {
            "id": "occ_jkl012",
            "startDateTime": "2024-07-12T18:00:00.000Z",
            "endDateTime": "2024-07-12T23:00:00.000Z"
          },
          {
            "id": "occ_mno345",
            "startDateTime": "2024-07-13T18:00:00.000Z",
            "endDateTime": "2024-07-13T23:00:00.000Z"
          }
        ],
        "eventGeoLocations": [
          {
            "geoLocation": {
              "description": "City Park Amphitheater",
              "locality": "Portland",
              "region": "OR",
              "country": "US",
              "relevanceScope": "venue"
            },
            "score": 0.95
          }
        ]
      }
    ]
  },
  "createdAt": "2024-01-15T12:00:00.000Z",
  "updatedAt": "2024-01-15T12:00:00.000Z"
}

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?​