# Create Research
Source: https://developer.happenstance.ai/api-reference/create-research

/openapi.json post /v1/research
Start a new person research request.

Include as many details as possible about the person in the description field
(full name, company, title, location, social media handles, etc.) for best results.

Requires sufficient credits. Returns 402 Payment Required if not enough credits.
Returns 429 Too Many Requests if you have 10 or more research requests currently running.



# Create Search
Source: https://developer.happenstance.ai/api-reference/create-search

/openapi.json post /v1/search
Search for people within specified groups and/or within a user's connections.

Use @mentions in your search query to filter results to a specific person's
connections (e.g., "engineers @Jane Smith knows"). Use the /v1/groups/{group_id}
endpoint to look up member names for @mentions.

Requires sufficient credits. Returns 402 Payment Required if not enough credits.
Returns 429 Too Many Requests if you have 10 or more search requests currently running.



# Find More Search
Source: https://developer.happenstance.ai/api-reference/find-more-search

/openapi.json post /v1/search/{search_id}/find-more
Find more results for a search.

Creates a new search that excludes all people from previous results in the search chain.
Uses the same query and settings as the original search.
Can only be called on the parent search (searches without a parent_search_id).

Requires sufficient credits. Returns 402 Payment Required if not enough credits.
Returns 429 Too Many Requests if you have 10 or more search requests currently running.



# Get Current User Profile
Source: https://developer.happenstance.ai/api-reference/get-current-user-profile

/openapi.json get /v1/users/me
Get the current user's profile.



# Get Group
Source: https://developer.happenstance.ai/api-reference/get-group

/openapi.json get /v1/groups/{group_id}
Get details of a specific group including its members.

Member names can be used as @mentions in search queries to filter results
to that person's connections (e.g., "engineers @Jane Smith knows").



# Get Groups
Source: https://developer.happenstance.ai/api-reference/get-groups

/openapi.json get /v1/groups



# Get Research
Source: https://developer.happenstance.ai/api-reference/get-research

/openapi.json get /v1/research/{research_id}
Get the status of a research request.



# Get Search
Source: https://developer.happenstance.ai/api-reference/get-search

/openapi.json get /v1/search/{search_id}
Get search results.

Returns the status and results of a search request.
Optionally provide a page_id to retrieve a specific page of results.



# Get Usage
Source: https://developer.happenstance.ai/api-reference/get-usage

/openapi.json get /v1/usage
Get credit balance, purchase history, usage history, and Auto Reload settings for the authenticated user.



# The Basics
Source: https://developer.happenstance.ai/api-reference/introduction

Happenstance API basic info

## API Resources

Our API is organized around REST principles with predictable, resource-oriented URLs.

### Base URL

```text theme={null}
https://api.happenstance.ai
```

### Authentication

All requests require an API key passed in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Note>
  API keys are sensitive credentials. Never share them publicly or commit them to version control.
</Note>

## OpenAPI Spec

Download the OpenAPI 3.1 specification to import into Postman, Insomnia, or any API client:

<Card title="Download OpenAPI Spec" icon="download" href="https://developer.happenstance.ai/openapi.json">
  openapi.json
</Card>

## Billing

Our API consumes credits for Search and Research operations:

* **Search**: 2 credits per search request (charged when search completes)
* **Research**: 1 credit per successful, completed research

You can add credits at any time from your <a href="https://happenstance.ai/integrations/keys">Settings</a> page.
You can also monitor your credits from the <a href="https://happenstance.ai/integrations/keys">Settings</a> page, or via the API's <a href="https://developer.happenstance.ai/api-reference/get-usage"> Get Usage</a> endpoint.

## Error Response Format

All errors follow the RFC 7807 Problem Details format:

```json theme={null}
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Description must not be empty",
  "instance": "/v1/research"
}
```

| Field      | Description                                              |
| ---------- | -------------------------------------------------------- |
| `type`     | A URI reference that identifies the problem type         |
| `title`    | A short, human-readable summary of the problem           |
| `status`   | The HTTP status code                                     |
| `detail`   | A human-readable explanation specific to this occurrence |
| `instance` | A URI reference that identifies the specific occurrence  |

## HTTP Status Codes

### 2xx Success

| Code     | Description       |
| -------- | ----------------- |
| `200 OK` | Request succeeded |

### 4xx Client Errors

<AccordionGroup>
  <Accordion title="400 Bad Request">
    The request was malformed or contains invalid parameters.

    **Common Causes:**

    * Missing required fields
    * Invalid JSON format
    * Empty or invalid values

    **Example:**

    ```json theme={null}
    {
      "type": "about:blank",
      "title": "Bad Request",
      "status": 400,
      "detail": "Description must not be empty",
      "instance": "/v1/research"
    }
    ```

    **Solution:** Check your request body against the API documentation
  </Accordion>

  <Accordion title="401 Unauthorized">
    Authentication failed - your API key is invalid or missing.

    **Common Causes:**

    * Missing `Authorization` header
    * Invalid API key
    * Revoked API key

    **Example:**

    ```json theme={null}
    {
      "type": "about:blank",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Invalid API key",
      "instance": "/v1/research"
    }
    ```

    **Solution:** Verify your API key is correct and not revoked
  </Accordion>

  <Accordion title="402 Payment Required">
    You don't have enough credits to perform this operation.

    **Common Causes:**

    * Account has zero credits
    * Insufficient credits for the requested operation

    **Example:**

    ```json theme={null}
    {
      "type": "about:blank",
      "title": "Payment Required",
      "status": 402,
      "detail": "Insufficient credits. You have 0 credits. This operation requires 2 credit(s).",
      "instance": "/v1/search"
    }
    ```

    **Solution:** Purchase more credits from your <a href="https://happenstance.ai/integrations/keys">Settings</a> page
  </Accordion>

  <Accordion title="403 Forbidden">
    You don't have permission to access the requested resource.

    **Common Causes:**

    * Attempting to access another user's research
    * Insufficient permissions for the operation

    **Example:**

    ```json theme={null}
    {
      "type": "about:blank",
      "title": "Forbidden",
      "status": 403,
      "detail": "Access denied",
      "instance": "/v1/research/550e8400-e29b-41d4-a716-446655440000"
    }
    ```

    **Solution:** Verify you have access to the resources you're requesting
  </Accordion>

  <Accordion title="404 Not Found">
    The requested resource doesn't exist.

    **Common Causes:**

    * Invalid endpoint URL
    * Resource has been deleted
    * Wrong research ID

    **Example:**

    ```json theme={null}
    {
      "type": "about:blank",
      "title": "Not Found",
      "status": 404,
      "detail": "Research request not found",
      "instance": "/v1/research/550e8400-e29b-41d4-a716-446655440000"
    }
    ```

    **Solution:** Check the resource ID and endpoint URL
  </Accordion>

  <Accordion title="422 Validation Error">
    The request body failed validation.

    **Common Causes:**

    * Missing required fields
    * Invalid field types
    * Fields that don't match expected format

    **Example:**

    ```json theme={null}
    {
      "type": "about:blank",
      "title": "Validation Error",
      "status": 422,
      "detail": "Field 'description' is required",
      "instance": "/v1/research"
    }
    ```

    **Solution:** Ensure all required fields are present and correctly formatted
  </Accordion>

  <Accordion title="429 Too Many Requests">
    You've exceeded the rate limit.

    **Common Causes:**

    * Making too many research requests per hour
    * Burst of requests in short time period

    **Example:**

    ```json theme={null}
    {
      "type": "about:blank",
      "title": "Too Many Requests",
      "status": 429,
      "detail": "Rate limit exceeded. Try again in 30 minutes.",
      "instance": "/v1/research"
    }
    ```

    **Solution:** Implement exponential backoff and respect rate limits
  </Accordion>
</AccordionGroup>

### 5xx Server Errors

<AccordionGroup>
  <Accordion title="500 Internal Server Error">
    Something went wrong on our end.

    **Example:**

    ```json theme={null}
    {
      "type": "about:blank",
      "title": "Internal Server Error",
      "status": 500,
      "detail": "Internal server error",
      "instance": "/v1/research"
    }
    ```

    **Solution:**

    * Retry the request with exponential backoff
    * If the issue persists, contact us on Discord
  </Accordion>

  <Accordion title="503 Service Unavailable">
    The API is temporarily unavailable.

    **Common Causes:**

    * Scheduled maintenance
    * Temporary outage
    * Database connection issues

    **Solution:**

    * Retry the request with exponential backoff
    * If the issue persists, contact [support](mailto:support@happenstance.ai)
  </Accordion>
</AccordionGroup>

## Error Handling Best Practices

### Check Status Codes

Always check the HTTP status code before parsing the response:

<CodeGroup>
  ```python Python theme={null}
  response = requests.post(url, headers=headers, json=data)

  if response.status_code == 200:
      result = response.json()
      # Handle success
  elif response.status_code == 401:
      # Handle authentication error
      print("Invalid API key")
  elif response.status_code == 402:
      # Handle insufficient credits
      print("Insufficient credits - purchase more at happenstance.ai/integrations/keys")
  elif response.status_code == 429:
      # Handle rate limit
      print("Rate limited, retry later")
  else:
      # Handle other errors
      error = response.json()
      print(f"Error: {error.get('title')} - {error.get('detail')}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  if (response.ok) {
    const result = await response.json();
    // Handle success
  } else if (response.status === 401) {
    // Handle authentication error
    console.error('Invalid API key');
  } else if (response.status === 402) {
    // Handle insufficient credits
    console.error('Insufficient credits - purchase more at happenstance.ai/integrations/keys');
  } else if (response.status === 429) {
    // Handle rate limit
    console.error('Rate limited, retry later');
  } else {
    const error = await response.json();
    console.error(`Error: ${error.title} - ${error.detail}`);
  }
  ```
</CodeGroup>

### Implement Retry Logic

For transient errors (429, 500, 503), implement exponential backoff:

```python theme={null}
import time
import requests

def make_request_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=data)

            if response.status_code == 200:
                return response.json()

            if response.status_code in [429, 500, 503]:
                # Exponential backoff: 1s, 2s, 4s
                wait_time = 2 ** attempt
                print(f"Retrying in {wait_time}s...")
                time.sleep(wait_time)
                continue

            # Don't retry client errors
            response.raise_for_status()

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

    raise Exception("Max retries exceeded")
```

### Validate Input Before Sending

Catch errors early by validating input:

```python theme={null}
def validate_research_request(description):
    if not description or not description.strip():
        raise ValueError("Description cannot be empty")

    # Include as much detail as possible for best results
    if len(description) < 10:
        print("Warning: Short descriptions may yield less accurate results")
```

### Log Errors for Debugging

Always log error details:

```python theme={null}
import logging

try:
    response = make_api_request(...)
except Exception as e:
    logging.error(f"API request failed: {e}", exc_info=True)
    # Handle error gracefully
```

## Common Error Scenarios

### Invalid API Key

```bash theme={null}
curl -X POST https://api.happenstance.ai/v1/research \
  -H "Authorization: Bearer invalid_key" \
  -H "Content-Type: application/json" \
  -d '{"description": "John Smith, CEO at Acme Corp"}'

# Response: 401
{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid API key",
  "instance": "/v1/research"
}
```

**Fix:** Use a valid API key from your account settings.

### Empty Description

```bash theme={null}
curl -X POST https://api.happenstance.ai/v1/research \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": ""}'

# Response: 400
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Description must not be empty",
  "instance": "/v1/research"
}
```

**Fix:** Provide a non-empty description with details about the person.

### Research Not Found

```bash theme={null}
curl -X GET https://api.happenstance.ai/v1/research/invalid-id \
  -H "Authorization: Bearer YOUR_KEY"

# Response: 404
{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Research request not found",
  "instance": "/v1/research/invalid-id"
}
```

**Fix:** Check that the research ID is correct and belongs to your account.

### Insufficient Credits

```bash theme={null}
curl -X POST https://api.happenstance.ai/v1/search \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "engineers at Google"}'

# Response: 402
{
  "type": "about:blank",
  "title": "Payment Required",
  "status": 402,
  "detail": "Insufficient credits. You have 0 credits. This operation requires 2 credit(s).",
  "instance": "/v1/search"
}
```

**Fix:** Purchase more credits from your [Settings](https://happenstance.ai/integrations/keys) page.

### Empty Search Results

```bash theme={null}
curl -X POST https://api.happenstance.ai/v1/search \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "engineers at Google", "include_my_connections": true}'

# Response: 200 (but with empty results)
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "COMPLETED",
  "results": []
}
```

**Cause:** You set `include_my_connections` or `include_friends_connections` to `true`, but you haven't uploaded any connections to search across.

**Fix:** Upload your LinkedIn connections at [happenstance.ai](https://happenstance.ai) before searching. Alternatively, search within specific groups by providing `group_ids`.

## Need Help?

<CardGroup>
  <Card title="Research Reference" icon="code" href="/api-reference/research/create-research">
    Detailed endpoint documentation
  </Card>

  <Card title="Support" icon="life-ring" href="https://happenstance.ai/contact">
    Contact our support team
  </Card>
</CardGroup>


# CLI
Source: https://developer.happenstance.ai/cli/install

Install and use the Happenstance CLI to search your network and research people from the terminal.

The [Happenstance CLI](https://pypi.org/project/happenstance/) (`hpn`) gives you access to the full Happenstance API from your terminal. All output is JSON, so you can pipe results to `jq` or integrate with scripts.

## Install

Requires Python 3.11+.

<Tabs>
  <Tab title="Homebrew">
    ```bash theme={null}
    brew tap happenstance-ai/tap
    brew install happenstance
    ```
  </Tab>

  <Tab title="uv">
    ```bash theme={null}
    uv tool install happenstance
    ```
  </Tab>

  <Tab title="pipx">
    ```bash theme={null}
    pipx install happenstance
    ```
  </Tab>

  <Tab title="pip">
    ```bash theme={null}
    pip install happenstance
    ```
  </Tab>
</Tabs>

## Configure

Get your API key from the [Settings](https://happenstance.ai/integrations/keys) page, then:

```bash theme={null}
hpn config set --api-key YOUR_API_KEY
```

The API key can also be provided via the `HPN_API_KEY` environment variable or the `--api-key` flag on any command. Priority: flag > env var > config file.

Verify your configuration:

```bash theme={null}
hpn config show
```

## Commands

| Command                        | Description                                    |
| ------------------------------ | ---------------------------------------------- |
| `hpn config set --api-key KEY` | Save your API key                              |
| `hpn config show`              | Show saved API key (masked)                    |
| `hpn search "query"`           | Search your network                            |
| `hpn search get ID`            | Get search results by ID                       |
| `hpn search find-more ID`      | Find additional results for an existing search |
| `hpn research "description"`   | Research a person                              |
| `hpn research get ID`          | Get research results by ID                     |
| `hpn friends`                  | List your friends (useful for @mentions)       |
| `hpn groups`                   | List your groups                               |
| `hpn groups get ID`            | Get group details and members                  |
| `hpn usage`                    | Show credit balance and usage                  |

## Search Your Network

```bash theme={null}
hpn search "engineers who have worked on AI infrastructure"
```

By default, the CLI waits for the search to complete and prints the results. Use `--no-wait` to get the search ID immediately and poll later:

```bash theme={null}
# Start search without waiting
hpn search "ML engineers in SF" --no-wait

# Poll for results later
hpn search get SEARCH_ID
```

### Scope Control

Control where to search with scope flags. When no flags are specified, all sources are searched.

```bash theme={null}
# Search only your own connections
hpn search "product managers" --my-connections

# Search only your friends' connections
hpn search "designers" --friends

# Search specific groups
hpn search "engineers" --groups "YC Founders" "AI Club"

# Combine scopes
hpn search "CTOs" --my-connections --groups "YC Founders"
```

### @Mentions

Filter results to a specific person's connections using @mentions in your query:

```bash theme={null}
hpn search "engineers @Jane Smith knows"
```

Use `hpn friends` or `hpn groups get ID` to look up names for @mentions.

### Find More Results

If a search returns `has_more: true`, get additional results (costs 2 credits):

```bash theme={null}
hpn search find-more SEARCH_ID
```

## Research a Person

```bash theme={null}
hpn research "Garry Tan, CEO of Y Combinator, @garrytan on Twitter"
```

Include as much detail as possible (full name, company, title, social handles) for best results. The CLI waits for the research to complete (up to 10 minutes).

Use `--no-wait` to return the research ID immediately:

```bash theme={null}
hpn research "Jane Smith, CTO at Acme Corp" --no-wait

hpn research get RESEARCH_ID
```

## Check Credits

```bash theme={null}
hpn usage
```

Returns your credit balance, purchase history, usage history, and auto-reload settings.

## Pipe to jq

All output is JSON. Combine with `jq` for filtering and formatting:

```bash theme={null}
# Get just the names from search results
hpn search "engineers" | jq '.results[].name'

# Pretty-print a research profile
hpn research "Jane Smith" | jq '.profile'

# List group names
hpn groups | jq '.groups[].name'
```

## Need Help?

<CardGroup>
  <Card title="Support" icon="life-ring" href="https://happenstance.ai/contact">
    Contact our support team
  </Card>
</CardGroup>


# ChatGPT
Source: https://developer.happenstance.ai/mcp/chatgpt

Connect Happenstance to ChatGPT

Happenstance is available as an official ChatGPT integration.

1. Visit the [Happenstance app page](https://chatgpt.com/apps/happenstance/asdk_app_69aa229aaca8819193b7dec8750221c9) on ChatGPT
2. Click **Connect**
3. Sign in to your Happenstance account

Once connected, you can ask ChatGPT things like:

* "Search my network for people who work in AI infrastructure"
* "Research Garry Tan, CEO of Y Combinator"
* "Find engineers in my YC group who have experience with distributed systems"
* "Check my Happenstance credit balance"

<Card title="All MCP Tools & Clients" icon="plug" href="/mcp/connect">
  See the full list of tools and setup for other clients
</Card>


# Claude
Source: https://developer.happenstance.ai/mcp/claude

Connect Happenstance to Claude

1. Open [Claude](https://claude.ai) and go to **Settings**
2. Navigate to the **Connectors** page
3. Click **Add custom connector**
4. Enter **Happenstance** as the name and `https://happenstance.ai/mcp/claude` as the URL
5. Click **Add**
6. Click **Connect** to log in to your Happenstance account

Once connected, you can ask Claude things like:

* "Search my network for people who work in AI infrastructure"
* "Research Garry Tan, CEO of Y Combinator"
* "Find engineers in my YC group who have experience with distributed systems"
* "Check my Happenstance credit balance"

The credit check includes your auto-reload status and a link to manage API credits at
[happenstance.ai/integrations/keys](https://happenstance.ai/integrations/keys).

<Card title="All MCP Tools & Clients" icon="plug" href="/mcp/connect">
  See the full list of tools and setup for other clients
</Card>


# Claude Code
Source: https://developer.happenstance.ai/mcp/claude-code

Connect Happenstance to Claude Code

Add to your Claude Code configuration:

```json theme={null}
{
  "mcpServers": {
    "happenstance": {
      "type": "http",
      "url": "https://happenstance.ai/mcp"
    }
  }
}
```

Once connected, you can ask Claude Code things like:

* "Search my network for people who work in AI infrastructure"
* "Research Garry Tan, CEO of Y Combinator"
* "Find engineers in my YC group who have experience with distributed systems"
* "Check my Happenstance credit balance"

<Card title="All MCP Tools & Clients" icon="plug" href="/mcp/connect">
  See the full list of tools and setup for other clients
</Card>


# MCP
Source: https://developer.happenstance.ai/mcp/connect

Connect Happenstance to AI assistants using the Model Context Protocol

The Happenstance MCP lets AI assistants search your network and research people on your behalf. It works with any client that supports the Model Context Protocol.

## What You Can Do

Once connected, your AI assistant can use these tools:

| Tool                              | Description                                                                 |
| --------------------------------- | --------------------------------------------------------------------------- |
| `search-network`                  | Search for people across your groups and connections                        |
| `get-search-results`              | Check status and retrieve results from a search                             |
| `find-more-results`               | Get additional results for an existing search (guarantees different people) |
| `research-person`                 | Start a detailed profile research on a person                               |
| `get-research-results`            | Check status and retrieve a research profile                                |
| `get-user`                        | Get your profile information and friends list                               |
| `get-groups`                      | List your Happenstance groups                                               |
| `get-group`                       | Get group details and full member list                                      |
| `get-credits`                     | Check your credit balance and usage                                         |
| `create-credits-checkout-session` | Create a Stripe checkout URL where supported                                |

<Note>
  Search and research run asynchronously. Your AI assistant will call the start tool, then poll the results tool until complete.
</Note>

### Finding More Results

Each search returns up to 30 results. If more are available, the response includes `has_more: true`. Your AI assistant can call `find-more-results` to get additional people — this guarantees different results by excluding everyone already returned. Each find-more request costs 2 credits.

## Connect

The MCP URL for most clients is:

```
https://happenstance.ai/mcp
```

For the Claude-optimized integration, use:

```
https://happenstance.ai/mcp/claude
```

Both endpoints authenticate with your Happenstance account via OAuth. Use the client-specific setup
guides below for the recommended URL and configuration.

See the setup guides for specific clients:

<CardGroup>
  <Card title="ChatGPT" icon="message" href="/mcp/chatgpt">
    Official ChatGPT integration
  </Card>

  <Card title="Claude" icon="robot" href="/mcp/claude">
    Anthropic's Claude assistant
  </Card>

  <Card title="Claude Code" icon="terminal" href="/mcp/claude-code">
    Bring Happenstance where you develop
  </Card>

  <Card title="OpenClaw" icon="lobster" href="/mcp/openclaw">
    Add the Happenstance skill
  </Card>
</CardGroup>

## Example Usage

Once connected, you can ask your AI assistant things like:

* "Search my network for people who work in AI infrastructure"
* "Research Garry Tan, CEO of Y Combinator"
* "Find engineers in my YC group who have experience with distributed systems"
* "Find engineers @Sarah Chen knows in my YC group"
* "Check my Happenstance credit balance"

## Billing

MCP tool calls consume credits the same as direct API calls:

* **Search**: 2 credits per search (including find-more requests)
* **Research**: 1 credit per completed research

The `get-credits` tool reports your auto-reload status and links to your
[Settings](https://happenstance.ai/integrations/keys) page. Checkout-session creation is available
in supported clients.

## Need Help?

<CardGroup>
  <Card title="Support" icon="life-ring" href="https://happenstance.ai/contact">
    Contact our support team
  </Card>
</CardGroup>


# OpenClaw
Source: https://developer.happenstance.ai/mcp/openclaw

Use Happenstance as a skill in OpenClaw-compatible agents

Happenstance is available as an [OpenClaw skill](https://clawhub.ai/dgoss28/happenstance) for AI coding agents.

1. Visit the [Happenstance skill page](https://clawhub.ai/dgoss28/happenstance) on ClawHub
2. Follow the install instructions for your agent
3. Set your `HAPPENSTANCE_API_KEY` environment variable

Get your API key from the [Settings](https://happenstance.ai/integrations/keys) page.

<Card title="All MCP Tools & Clients" icon="plug" href="/mcp/connect">
  See the full list of tools and setup for other clients
</Card>


# Quickstart
Source: https://developer.happenstance.ai/quickstart

Get started with the Happenstance API in minutes

## Prerequisites

Before you begin, make sure you have:

* A Happenstance account
* Your API key (generated from <a href="https://happenstance.ai/integrations/keys">Settings</a>)

## Make Your First Request

<Tabs>
  <Tab title="Search Your Network">
    ### 1. Submit a Search Request

    Search for relevant people within your groups and connections:

    ```bash theme={null}
    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
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "url": "https://happenstance.ai/search/a1b2c3d4-5678-90ab-cdef-1234567890ab"
    }
    ```

    <Note>
      You can also search within specific groups by including `group_ids` - get your group IDs from the `/v1/groups` endpoint.
    </Note>

    <Tip>
      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.
    </Tip>

    ### 2. Poll for Results

    Search runs asynchronously. Poll the GET endpoint until `status` is `COMPLETED`:

    ```bash theme={null}
    curl -X GET https://api.happenstance.ai/v1/search/a1b2c3d4-5678-90ab-cdef-1234567890ab \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    **Response (in progress):**

    ```json theme={null}
    {
      "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):**

    ```json theme={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
    }
    ```

    <Tip>
      Poll every 5-10 seconds. Search typically completes within 30-60 seconds.
    </Tip>

    ### 3. Find More Results (Optional)

    If `has_more` is `true`, you can request additional results:

    ```bash theme={null}
    curl -X POST https://api.happenstance.ai/v1/search/a1b2c3d4-5678-90ab-cdef-1234567890ab/find-more \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Research A Person">
    ### 1. Submit a Research Request

    Generate a detailed profile about a person:

    ```bash theme={null}
    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"
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "id": "547e404b-0129-4400-b42d-038cca184414",
      "url": "https://happenstance.ai/research/547e404b-0129-4400-b42d-038cca184414"
    }
    ```

    <Note>
      Include as much detail as possible (full name, company, title, social handles) for best results.
    </Note>

    ### 2. Poll for Completion

    Research runs asynchronously. Poll the GET endpoint until `status` is `COMPLETED`:

    ```bash theme={null}
    curl -X GET https://api.happenstance.ai/v1/research/547e404b-0129-4400-b42d-038cca184414 \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    **Response (in progress):**

    ```json theme={null}
    {
      "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):**

    ```json theme={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/"
          ]
        }
      }
    }
    ```

    <Tip>
      Poll every 5-10 seconds. Research typically completes within 1-3 minutes.
      Status can be `RUNNING`, `COMPLETED`, `FAILED`, or `FAILED_AMBIGUOUS`.
    </Tip>
  </Tab>
</Tabs>

## Next Steps

<CardGroup>
  <Card title="The Basics" icon="book" href="/api-reference/introduction">
    Learn about the API
  </Card>

  <Card title="Support" icon="life-ring" href="https://happenstance.ai/contact">
    Contact our support team
  </Card>
</CardGroup>