Prerequisites
Before you begin, make sure you have:- A Happenstance account
- Your API key (generated from Settings)
Make Your First Request
- Search Your Network
- Research A Person
1. Submit a Search Request
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
}'
{
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"url": "https://happenstance.ai/search/a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
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.2. Poll for Results
Search runs asynchronously. Poll the GET endpoint untilstatus is COMPLETED:curl -X GET https://api.happenstance.ai/v1/search/a1b2c3d4-5678-90ab-cdef-1234567890ab \
-H "Authorization: Bearer YOUR_API_KEY"
{
"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
}
{
"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.
3. Find More Results (Optional)
Ifhas_more is true, you can request additional results:curl -X POST https://api.happenstance.ai/v1/search/a1b2c3d4-5678-90ab-cdef-1234567890ab/find-more \
-H "Authorization: Bearer YOUR_API_KEY"
1. Submit a Research Request
Generate a detailed profile about a person:curl -X POST https://api.happenstance.ai/v1/research \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "Garry Tan Y Combinator"
}'
{
"id": "547e404b-0129-4400-b42d-038cca184414",
"url": "https://happenstance.ai/research/547e404b-0129-4400-b42d-038cca184414"
}
Include as much detail as possible (full name, company, title, social handles) for best results.
2. Poll for Completion
Research runs asynchronously. Poll the GET endpoint untilstatus is COMPLETED:curl -X GET https://api.happenstance.ai/v1/research/547e404b-0129-4400-b42d-038cca184414 \
-H "Authorization: Bearer YOUR_API_KEY"
{
"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
}
{
"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.Next Steps
The Basics
Learn about the API
Support
Contact our support team