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 ar...