# Happenstance

> Search your professional network and research people using Happenstance. Find relevant professionals across your groups and connections with mutual connection strength, then get comprehensive profiles.

- Skill: `happenstance-ai/happenstance` (Agent Skill)
- Install (CLI): `npx skillmds@latest add happenstance-ai/happenstance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/happenstance-ai/happenstance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: happenstance-ai (https://skillmd.com/u/happenstance-ai)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/happenstance-ai/happenstance

---


# Happenstance

Search your network and get detailed research profiles on people using Happenstance.

Documentation: https://developer.happenstance.ai

## Credits

- **Search**: 2 credits per search (including find-more)
- **Research**: 1 credit per completed research
- Always call `get-credits` before starting searches or research to check balance
- Use `create-credits-checkout-session` if the user needs more credits

## Workflows

### Search for People

Searches can pull from three sources, controlled by parameters:

- **Groups** (`includeGroups`): Search across the user's Happenstance groups. Searches all groups by default, or pass specific `groups` (array of group IDs) to narrow scope. Call `get-groups` to list available groups and their IDs.
- **Connections** (`includeConnections`): Search the user's direct connections.
- **Friends** (`includeFriends`): Search connections of the user's friends.

All three are enabled by default. The user may want to search only specific sources — for example, only within a particular group, or only their direct connections.

**Steps:**

1. If the user wants to search specific groups, call `get-groups` first to list available groups and get their IDs. Use `get-group` to see members of a specific group.
2. Call `search-network` with a natural language query and the desired source parameters — returns a `searchId`
3. Poll with `get-search-results` using the `searchId` until status is `completed`
4. If `has_more` is true and the user wants more, call `find-more-results` (not a new search) — returns a `pageId`
5. Poll with `get-search-results` using both the original `searchId` and the `pageId`

When a user asks "who do I know that..." set `includeGroups: false`, `includeFriends: false`, `includeConnections: true`.

### Research a Person

1. Call `research-person` with a description including as many details as possible (full name, company, title, social handles) — returns a `researchId`
2. Poll with `get-research-results` using the `researchId` until status is `completed`

### Use @Mentions for Targeted Search

To search a specific person's connections, @mention them in the query:
- First call `get-groups` and `get-group` to look up member names, or `get-user` for friends
- Then search with: `"engineers @Jane Smith knows"`

## Presenting Results

### Search Results

Each result includes `name`, `current_title`, `current_company`, `summary`, `socials` (with `happenstance_url`, `linkedin_url`, `twitter_url`), `mutuals`, and `traits`.

- **Highlight mutual connections**: Results include mutuals with relationship strength — surface the strongest mutual connections to help the user find the warmest intro path
- **Include profile links**: Always link to the person's Happenstance profile URL
- **Show relevance**: Include the person's summary and matching traits

### Research Results

A completed research profile includes:
- `person_metadata`: full name, alternate names, profile URLs, locations, tagline
- `employment`: career history with companies, titles, dates, descriptions
- `education`: universities, degrees, dates
- `projects`: notable projects with descriptions and URLs
- `writings`: publications with titles, dates, URLs
- `hobbies`: personal interests
- `summary`: overall summary with supporting source URLs

Summarize the profile and link to sources when presenting.

## Tips

- Search typically completes in 30-60 seconds. Research takes 1-3 minutes.
- Each search returns up to 30 results. Use `find-more-results` for additional pages.
- The more data sources the user connects, the better the search results.