Search for relevant people within your groups and connections:
curl -X POST https://api.happenstance.ai/v1/search \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "engineers who have worked on AI infrastructure", "include_my_connections": true }'
You can also search within specific groups by including group_ids - get your group IDs from the /v1/groups endpoint.
Use @mentions in your query to filter results to a specific person’s connections.
For example: "engineers @Jane Smith knows". Use the /v1/groups/{group_id} endpoint
to look up member names.
Search runs asynchronously. Poll the GET endpoint until status is COMPLETED:
curl -X GET https://api.happenstance.ai/v1/search/a1b2c3d4-5678-90ab-cdef-1234567890ab \ -H "Authorization: Bearer YOUR_API_KEY"
Response (in progress):
{ "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "url": "https://happenstance.ai/search/a1b2c3d4-5678-90ab-cdef-1234567890ab", "status": "RUNNING", "text": "engineers who have worked on AI infrastructure", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:05Z", "results": null}
Response (completed):
{ "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "url": "https://happenstance.ai/search/a1b2c3d4-5678-90ab-cdef-1234567890ab", "status": "COMPLETED", "text": "engineers who have worked on AI infrastructure", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:45Z", "results": [ { "id": "person-uuid-1", "name": "Jane Smith", "current_title": "Staff Engineer", "current_company": "OpenAI", "summary": "Led infrastructure team building distributed training systems...", "weighted_traits_score": 2.5, "socials": { "happenstance_url": "https://happenstance.ai/u/person-uuid-1", "linkedin_url": "https://linkedin.com/in/janesmith" } } ], "has_more": true}
Poll every 5-10 seconds. Search typically completes within 30-60 seconds.
Research runs asynchronously. Poll the GET endpoint until status is COMPLETED:
curl -X GET https://api.happenstance.ai/v1/research/547e404b-0129-4400-b42d-038cca184414 \ -H "Authorization: Bearer YOUR_API_KEY"
Response (in progress):
{ "id": "547e404b-0129-4400-b42d-038cca184414", "status": "RUNNING", "query": "Garry Tan Y Combinator", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:05Z", "profile": null}
Response (completed):
{ "id": "547e404b-0129-4400-b42d-038cca184414", "status": "COMPLETED", "query": "Garry Tan Y Combinator", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:32:15Z", "profile": { "person_metadata": { "full_name": "Garry Tan", "alternate_names": [], "profile_urls": [ "https://www.ycombinator.com/people/garry-tan", "https://x.com/garrytan", "https://www.linkedin.com/in/garrytan" ], "current_locations": [ { "location": "San Francisco, California", "urls": ["https://www.forbes.com/profile/garry-tan/"] } ], "tagline": "President and CEO of Y Combinator, entrepreneur, and investor" }, "employment": [ { "company_name": "Y Combinator", "job_title": "President and CEO", "start_date": "2022", "end_date": null, "description": "Leads Y Combinator, the world's most successful startup accelerator." } ], "summary": { "text": "Garry Tan is a prominent Silicon Valley entrepreneur, investor, and the current President and CEO of Y Combinator...", "urls": [ "https://www.ycombinator.com/people/garry-tan", "https://www.forbes.com/profile/garry-tan/" ] } }}
Poll every 5-10 seconds. Research typically completes within 1-3 minutes.
Status can be RUNNING, COMPLETED, FAILED, or FAILED_AMBIGUOUS.
