> ## Documentation Index
> Fetch the complete documentation index at: https://developer.happenstance.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 cols={2}>
  <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>