Events

Events are conferences, meetups, trade shows, and other gatherings that HumanConnection can search for. They are the highest-conversion meeting context: when two people are already at the same event, a conversation feels natural, not transactional.

Overview

A cold coffee invitation has a 20% show rate. A “let’s catch up at SaaStr” has 85%. Events give your agent a reason to connect that doesn’t feel like a pitch — and the shared context (same industry, same interests, same room) accelerates trust in ways that no email thread can.

Use search_events to find upcoming events near your lead, then reference them in your service request or meeting booking.

The Event type

1
interface Event {
2
  id: string;          // Unique identifier, prefixed with "evt_"
3
  name: string;        // Name of the event
4
  category: string;    // Category (e.g. "conference", "meetup", "tradeshow")
5
  location: {
6
    name: string;      // Venue name
7
    address: string;   // Street address
8
    city: string;      // City
9
    lat: number;       // Latitude
10
    lng: number;       // Longitude
11
  };
12
  starts_at: string;   // ISO 8601 start datetime
13
  ends_at: string;     // ISO 8601 end datetime
14
  attendee_count: number; // Expected number of attendees
15
  url: string;         // Event website URL
16
  tags: string[];      // Tags for filtering
17
}

search_events parameters

Example usage

1
import { search_events } from '@humanconnection/toolkit';
2
3
const events = await search_events({
4
  location: { city: "San Francisco" },
5
  radius_km: 50,
6
  category: "conference",
7
  date_after: "2026-04-01T00:00:00Z",
8
  date_before: "2026-06-30T23:59:59Z"
9
});

Example response

1
{
2
  "data": [
3
    {
4
      "id": "evt_9f8e7d6c5b4a3e2d",
5
      "name": "SaaStr Annual 2026",
6
      "category": "conference",
7
      "location": {
8
        "name": "San Mateo Event Center",
9
        "address": "1346 Saratoga Dr, San Mateo, CA 94403",
10
        "city": "San Mateo",
11
        "lat": 37.5630,
12
        "lng": -122.3255
13
      },
14
      "starts_at": "2026-05-12T08:00:00Z",
15
      "ends_at": "2026-05-14T18:00:00Z",
16
      "attendee_count": 15000,
17
      "url": "https://www.saastr.com/annual",
18
      "tags": ["saas", "b2b", "enterprise", "cloud"]
19
    }
20
  ],
21
  "total": 1,
22
  "has_more": false
23
}

Data source

Events are sourced from the Luma discover API. The implementation resolves city names to coordinates using a built-in lookup table (covering major cities like Paris, London, New York, San Francisco, Dubai, etc.) or falls back to SearXNG-based coordinate resolution.

How events relate to other resources

• Meetings: A meeting can reference an event via event_id, meaning it takes place at that event’s venue. Event-based meetings have the highest show rates.
• Services: A service request can specify a preferred_event_id to target a specific event.
• Humans: After finding a person with search_humans, events near them provide the most natural meeting context.
• Places: When no relevant event exists, places provide an always-available alternative.

Best practices

• Search broadly by date range. Look 1-3 months ahead to find upcoming opportunities.
• Use events as conversation context. Even if the meeting doesn’t happen at the event itself, mentioning a shared event makes outreach warmer and more personal.
• Match event category to lead industry. A fintech lead is more likely to attend a finance or startup event.
• Combine with search_humans. Find the person first, then search for events near their location.
• Prefer events over cold places. A shared event creates an implicit connection — “we’re both here because we care about the same things.” That’s the foundation of a relationship, not just a transaction.