# Find Events (`hypebridge/find-events`) Actor

Queries multiple event platforms for a given city and category, returning a single normalized dataset of scheduled events. Supported platforms include Eventbrite, Meetup, Luma, Dice, Eventnoire, Posh, Prekindle, and Shotgun.

- **URL**: https://apify.com/hypebridge/find-events.md
- **Developed by:** [Hypebridge](https://apify.com/hypebridge) (community)
- **Categories:** E-commerce, Integrations, Automation
- **Stats:** 5 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 orchestration units

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### What does Find Events do?

Find Events queries multiple primary event platforms for a given city and category, returning a single normalized dataset of scheduled events. Supported platforms include Eventbrite, Meetup, Luma, Partiful, Dice, Eventnoire, Posh, Prekindle, Shotgun, Showpass, Sympla, RunSignup, and Eventeny. The actor matches search parameters, fetches listings, and deduplicates identical events across sources.

### Core Capabilities

- **Unified Querying**: Retrieve events across platforms with a single request, eliminating the need to configure and coordinate multiple individual crawlers.
- **Data Standardization**: All outputs use a single schema regardless of the source platform, including standardized ISO UTC timestamps, locations, and pricing fields.
- **Event Deduplication**: The system merges identical listings found on multiple platforms using title, date, city, and venue heuristics.
- **Local-Affinity Routing**: The actor first limits sources to those that serve the requested country or metro, then prioritizes sources that have historically returned useful local results for that city and category.

### What data can Find Events extract?

| Field | Type | Description |
|-------|------|-------------|
| `title` | String | Event name |
| `platform` | String | Source platform (e.g. `meetup`, `dice`) |
| `sourceUrl` | String | Link to the original event page |
| `category` | String | Canonical category you searched for |
| `startDateTimeUtc` | String | Start time in UTC (ISO 8601) |
| `localDate` | String | Event date in the city's timezone |
| `venueName` / `address` | String | Where the event takes place |
| `city` / `state` / `country` | String | Resolved location |
| `requestedCity` / `locationMatchQuality` | String | Requested city and whether the event was an exact or nearby location match |
| `priceMin` / `priceMax` / `isFree` | Number / Boolean | Ticket pricing when available |
| `imageUrl` | String | Event cover image |
| `description` | String | Event description (richer with details enabled) |
| `sourceFields` | Object | The untouched original record from the source platform |

Duplicates appearing on multiple platforms are merged using title, date, city, and venue.

### Run Configuration

1. Enter the target location in the `city` field (e.g., `Dallas, TX` or `Berlin`).
2. Select a `category` (e.g., `music`, `technology`) and a `timeWindow`.
3. Specify the `maxEvents` limit to define the target number of results.
4. Click **Start** to run the actor and retrieve findings from the **Dataset** tab.

### Cost Structure

Total run costs consist of the orchestration fee for this actor and the fees of the platform-specific crawlers executed on your behalf.

#### 1. Orchestration Fee (Pay Per Event)

| Metric | Cost |
|---|---|
| Run Start | $0.005 |
| Event Delivered | $0.002 ($2.00 per 1,000 events) |

#### 2. Platform Crawlers (Billed Separately)

This actor triggers child runs of platform crawlers (such as Meetup, Luma, or Dice) using your Apify account resources. Platform crawlers charge their own pay-per-event fees, which typically range from $0.002 to $0.011 per event depending on the platform and whether full event details are retrieved. These appear as separate runs on your Apify usage logs.

#### Estimating Total Cost

Combined estimates vary based on city size, category, and the mix of active sources.

| Request Size | Orchestration Fee | Platform Crawlers | Estimated Total |
|---|---|---|---|
| 10 events | ~$0.03 | ~$0.08 to $0.15 | **~$0.10 to $0.18** |
| 50 events | ~$0.11 | ~$0.30 to $0.50 | **~$0.40 to $0.60** |
| 50 events with details | ~$0.11 | ~$0.60 to $0.95 | **~$0.70 to $1.05** |

#### Volume Controls

- **Max Events**: Set `maxEvents` to limit the volume of processed and delivered items.
- **Event Details**: Setting `getEventDetails` to false reduces platform crawler costs by skipping detailed sub-pages, fetching only the index listing.

You do not need to compare platform prices or classify sources as cheap or expensive. Source selection is based on geographic applicability and learned local yield. The actor still caps child concurrency, child-run count, and requested records so fan-out remains bounded.

### Input

See the **Input** tab for the full schema. Key fields:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `city` | String | `Dallas, TX` | Free-form city, optionally with state or country. |
| `category` | String | `all` | Event category: `music`, `nightlife`, `technology`, `business`, `food_drink`, `arts_culture`, `comedy`, `sports_fitness`, `wellness`, `community_culture`, `family_education`. |
| `timeWindow` | String | `this_month` | `this_week`, `this_month`, or `all`. |
| `maxEvents` | Integer | `50` | Maximum unique events to return. |
| `platforms` | Array | all supported defaults | Optional source allowlist. Regional sources run only where they apply: Sympla in Brazil; Showpass in Canada and the US; RunSignup in the US and Canada; Eventeny in the US and Canada; Partiful in supported metros. |
| `getEventDetails` | Boolean | `false` | Fetch full event pages for richer data. Date-bounded Eventbrite and Shotgun searches enable the minimum detail needed for reliable date filtering. |
| `childRunTimeoutSecs` | Integer | auto | Max seconds to wait for any one platform. |

#### Example input

```json
{
  "city": "San Francisco, CA",
  "category": "music",
  "timeWindow": "this_week",
  "maxEvents": 50,
  "platforms": ["dice", "shotgun", "luma"],
  "getEventDetails": true
}
```

### Output

Saved to the **Dataset** tab. Download as JSON, CSV, Excel, or HTML.

Each item includes:

- **Event**: title, description, category, start/end times (UTC and local), status
- **Location**: venue, address, city, state, country, coordinates
- **Pricing**: priceMin, priceMax, currency, isFree
- **Provenance**: platform, sourceUrl, scrapedAt, plus the raw source record in `sourceFields`

#### Sample output

```json
{
  "id": "luma:evt_123",
  "platform": "luma",
  "sourceUrl": "https://lu.ma/ai-builders-dallas",
  "category": "technology",
  "title": "AI Builders Hackathon & Meetup",
  "description": "Join us for an exciting evening of building agentic apps.",
  "startDateTimeUtc": "2026-07-15T23:00:00.000Z",
  "localDate": "2026-07-15",
  "city": "Dallas",
  "state": "TX",
  "venueName": "Capital One Innovation Hub",
  "address": "1900 Pacific Ave, Dallas, TX 75201",
  "priceMin": 0,
  "isFree": true,
  "imageUrl": "https://images.lumacdn.com/event-cover.jpg",
  "scrapedAt": "2026-07-02T23:12:00.000Z"
}
```

### Operational Guidelines

- **Selecting Platforms**: Leave all platforms selected. The actor automatically removes sources that do not serve the location and prioritizes proven city-local sources. Use the field only as an allowlist when you explicitly need a source subset.
- **Freshness and Volume**: Use `timeWindow: "this_week"` for time-sensitive listings, or `all` to capture long-term scheduled data.
- **Details vs. Listings**: Enable `getEventDetails` only when rich descriptions, ticket prices, or lineups are required for your database. Skipping details keeps platform crawler costs at their baseline rate.

### FAQ

#### Legal and Compliance

Find Events extracts publicly available event listings. Check the Terms of Service for each source platform and ensure your data collection complies with applicable regulations.

#### Cost Variation Across Runs

Platform distribution varies by city. In smaller markets, the actor may try more locally applicable sources to fulfill the requested event limit. Use `maxEvents` and the Apify run charge limit as the bounded controls.

#### Low Event Volume Behavior

If a city contains fewer events than the `maxEvents` value, the crawler terminates after exhausting all active platforms. You are billed for the $0.005 start fee and the events successfully delivered.

### Support and Feedback

- Report bugs or submit feature requests through the **Issues** tab.
- Reference the **API** tab for details on running this actor programmatically.

#### Privacy and Data Protection Disclaimer

This crawler only extracts public event listings. It does not extract private user details such as personal email addresses, gender, or user locations. Depending on the listings, the returned datasets may contain public personal data (e.g., event host names). Users are responsible for ensuring that their data collection and storage complies with GDPR, CCPA, and other local data protection regulations. Consult legal counsel if you are uncertain about compliance requirements.

# Actor input Schema

## `category` (type: `string`):

Canonical event category used to route across supported platforms.

## `city` (type: `string`):

Free-form city, optionally including state or country, for example Dallas, TX or New York.

## `timeWindow` (type: `string`):

Filter events to a simple time window. Resolved to concrete start/end dates internally using the resolved city timezone.

## `maxEvents` (type: `integer`):

Maximum number of normalized events to return across all platforms.

## `getEventDetails` (type: `boolean`):

Ask supported child actors to enrich listings with full event-page details. Unsupported child actors ignore this setting.

## `platforms` (type: `array`):

Optional source allowlist. Regional sources are automatically used only where they serve the requested city or country.

## `minUsefulResults` (type: `integer`):

If a platform returns fewer records than this and maxEvents is not reached, continue to the next platform.

## `childRunTimeoutSecs` (type: `integer`):

Maximum seconds to wait for any one downstream actor.

## `debugMode` (type: `boolean`):

Store route plans, child inputs, pricing decisions, and skipped-platform reasons in the key-value store.

## Actor input object example

```json
{
  "category": "all",
  "city": "Dallas, TX",
  "timeWindow": "this_week",
  "maxEvents": 50,
  "getEventDetails": false,
  "platforms": [
    "luma",
    "meetup",
    "partiful",
    "dice",
    "eventnoire",
    "posh",
    "prekindle",
    "shotgun",
    "eventbrite",
    "showpass",
    "sympla",
    "runsignup",
    "eventeny"
  ],
  "minUsefulResults": 3,
  "childRunTimeoutSecs": 240,
  "debugMode": false
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset containing aggregated event records from multiple platforms.

## `files` (type: `string`):

Key-value store files created when debug mode is enabled.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "category": "all",
    "city": "Dallas, TX",
    "timeWindow": "this_week",
    "maxEvents": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("hypebridge/find-events").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "category": "all",
    "city": "Dallas, TX",
    "timeWindow": "this_week",
    "maxEvents": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("hypebridge/find-events").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "category": "all",
  "city": "Dallas, TX",
  "timeWindow": "this_week",
  "maxEvents": 50
}' |
apify call hypebridge/find-events --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,hypebridge/find-events"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/XIUAyRsGZ5I3g1kxi/builds/Yzxnw9uJEF4ejmSmy/openapi.json