happenstance

# 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:** ```bash 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:** ```json {"id": "search-uuid", "url": "https://happenstance.ai/search/search-uuid"} ``` **Poll for results** (every 5-10 seconds until status is `COMPLETED` or `FAILED`): ```bash 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. ```bash curl -s -X POST https://api.happenstance.ai/v1/search/SEARCH_ID/find-more \ -H "Authorization: Bearer $HAPPENSTANCE_API_KEY" ``` **Response:** ```json {"page_id": "page-uuid", "parent_search_id": "search-uuid"} ``` Then poll with the page_id: ```bash 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:** ```bash curl -s -X POST https://api.happenstance.ai/v1/research \ -H "Authorization: Bearer $HAPPENSTANCE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"description": "Garry Tan, CEO of Y Combinator, @garrytan on Twitter"}' ``` Include as many details as possible (full name, company, title, location, social handles) for best results. **Response:** ```json {"id": "research-uuid"} ``` **Poll for results** (every 5-10 seconds until status is `COMPLETED`, `FAILED`, or `FAILED_AMBIGUOUS`): ```bash curl -s https://api.happenstance.ai/v1/research/RESEARCH_ID \ -H "Authorization: Bearer $HAPPENSTANCE_API_KEY" ``` **Completed response includes a `profile` object with:** - `person_metadata`: `full_name`, `alternate_names`, `profile_urls`, `current_locations`, `tagline` - `employment`: array of jobs with `company_name`, `job_title`, `start_date`, `end_date`, `description` - `education`: array with `university_name`, `degree`, `start_date`, `end_date` - `projects`: array with `title`, `description`, `urls` - `writings`: array of publications with `title`, `description`, `date`, `urls` - `hobbies`: array with `description` - `summary`: overall `text` summary with supporting `urls` ### 4. List Groups Get the groups you can search within: ```bash curl -s https://api.happenstance.ai/v1/groups \ -H "Authorization: Bearer $HAPPENSTANCE_API_KEY" ``` Returns `{"groups": [{"id": "uuid", "name": "Group Name"}, ...]}`. ### 5. Check Credits and Usage ```bash curl -s https://api.happenstance.ai/v1/usage \ -H "Authorization: Bearer $HAPPENSTANCE_API_KEY" ``` Returns `balance_credits`, `has_credits`, `purchases`, `usage` history, and `auto_reload` settings. ## Error Handling Errors use RFC 7807 format: ```json {"type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Description must not be empty", "instance": "/v1/research"} ``` Key status codes: - `401`: Invalid or missing API key - `402`: Insufficient credits - `429`: Too many concurrent requests (max 10 running searches or research requests) - `500`/`503`: Server error, retry with backoff ## Tips - Always check credits before starting multiple searches or research requests. - Search typically completes in 30-60 seconds. Research takes 1-3 minutes. - Each search returns up to 30 results. Use find-more for additional pages. - When presenting search results, include the person's name, title, company, summary, and Happenstance profile link. - When presenting research, summarize the profile and link to sources. - The more data sources the user connects, the better the search results.