Happenstance

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

Documentation: https://developer.happenstance.ai

Authentication

All requests require the HAPPENSTANCE_API_KEY environment variable. Pass it as a Bearer token:

Authorization: Bearer $HAPPENSTANCE_API_KEY

Base URL: https://api.happenstance.ai

Billing

• Search: 2 credits per search (including find-more)
• Research: 1 credit per completed research
• Check balance with GET /v1/usage
• Purchase credits at https://happenstance.ai/settings/api

Available Operations

1. Search Your Network

Search for people across groups and connections. Searches run asynchronously.

Start a search:

curl -s -X POST https://api.happenstance.ai/v1/search \
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "engineers who have worked on AI infrastructure",
    "include_my_connections": true,
    "include_friends_connections": true
  }'

You can also search within specific groups by adding "group_ids": ["uuid1", "uuid2"]. Get group IDs from GET /v1/groups.

At least one search source is required: group_ids, include_my_connections: true, or include_friends_connections: true.

Response:

{"id": "search-uuid", "url": "https://happenstance.ai/search/search-uuid"}

Poll for results (every 5-10 seconds until status is COMPLETED or FAILED):

curl -s https://api.happenstance.ai/v1/search/SEARCH_ID \
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

Completed response includes:

• status: RUNNING, COMPLETED, or FAILED
• results: array of people, each with id, name, current_title, current_company, summary, weighted_traits_score, socials (with happenstance_url, linkedin_url, twitter_url), mutuals, and traits
• has_more: boolean indicating if more results are available
• mutuals: top-level array of mutual connections (results reference these by index)
• traits: top-level array of trait definitions (results reference these by index)

2. Find More Results

When has_more is true on a completed search, get additional results that exclude all previously returned people. Costs 2 credits.

curl -s -X POST https://api.happenstance.ai/v1/search/SEARCH_ID/find-more \
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

Response:

{"page_id": "page-uuid", "parent_search_id": "search-uuid"}

Then poll with the page_id:

curl -s "https://api.happenstance.ai/v1/search/SEARCH_ID?page_id=PAGE_ID" \
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

3. Research a Person

Get a detailed professional profile for a specific person. Runs asynchronously.

Start research: