---
title: "Get Search"
method: GET
path: "/v1/search/{search_id}"
---

# Get Search

`GET /v1/search/{search_id}`

## Request

- Base URL: `https://api.happenstance.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.happenstance.ai/v1/search/{search_id}`
- Auth: HTTP bearer

Get search results.

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

## Path parameters

- `search_id` string, required

## Query parameters

- `page_id` string, nullable

## Response `200`

Successful Response

- GetSearchResponseV1: Response from GET /v1/search/{id} - retrieving search status and results.
  - `id` string, required: Unique identifier for the search request
  - `url` string, required: URL to view the search results on Happenstance (points to parent search for continued searches)
  - `status` string, required: Status of the search (RUNNING, COMPLETED, FAILED)
  - `text` string, required: Original search query text
  - `created_at` string, required: Timestamp when search was created (ISO 8601 format)
  - `updated_at` string, required: Timestamp when search was last updated (ISO 8601 format)
  - `group_ids` string[]: List of group IDs that were searched
  - `include_friends_connections` boolean: Whether the search included friends' connections
  - `include_my_connections` boolean: Whether the search included the user's own connections
  - `mutuals` SearchMutualV1[], nullable: All unique mutual connections across results. Results reference these by index.
    - `index` integer, required: Index of this mutual in the mutuals array
    - `id` string, required: Unique identifier for the mutual connection
    - `name` string, required: Name of the mutual connection
    - `happenstance_url` string, required: URL to the mutual's Happenstance profile
  - `traits` SearchTraitV1[], nullable: All trait definitions for this search. Results reference these by index.
    - `index` integer, required: Index of this trait in the traits array
    - `header` string, required: Short label for the trait (e.g., 'Undergrad')
    - `description` string, nullable: Full trait description explaining what was evaluated
  - `results` SearchPersonV1[], nullable: Search results (only populated when status is COMPLETED)
    - `id` string, required: Unique identifier for the person
    - `name` string, required: Person's name
    - `weighted_traits_score` number, required: Overall relevance score based on trait evaluations. Calculated as sum of trait scores minus penalties for traits scored zero. Can be negative.
    - `current_title` string, nullable: Current job title
    - `current_company` string, nullable: Current company
    - `summary` string, nullable: AI-generated summary of why this person matches
    - `socials` SocialsV1, required: Profile URLs for a person
      - `happenstance_url` string, required: URL to the person's Happenstance profile
      - `linkedin_url` string, nullable: LinkedIn profile URL
      - `twitter_url` string, nullable: Twitter/X profile URL
      - `instagram_url` string, nullable: Instagram profile URL
    - `mutuals` SearchMutualRefV1[], nullable: References to mutual connections (indices into top-level mutuals array)
      - `index` integer, required: Index into the top-level mutuals array
      - `affinity_score` number, nullable: Affinity score indicating connection strength between the mutual and this person. Higher values indicate stronger connections.
    - `traits` SearchTraitScoreV1[], nullable: Trait scores for this person (indices into top-level traits array)
      - `index` integer, required: Index into the top-level traits array
      - `score` number, required: Score for this trait (0, 0.5, or 1)
      - `evidence` string, nullable: Supporting quote or citation from the person's profile
  - `page_id` string, nullable: Page identifier for the current result page. Null for the first page (the parent search itself). For subsequent pages, this is the page_id returned by POST /v1/search/{id}/find-more.
  - `next_page` string, nullable: Page identifier for the next result page. Use as the page_id query parameter on GET /v1/search/{id}?page_id={next_page} to retrieve the next page. Null if no next page exists.
  - `has_more` boolean: Whether more results may be available via POST /v1/search/{id}/find-more. Searches return up to 30 results at a time.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Payment Required
- `403`: Forbidden
- `404`: Not Found
- `410`: Gone
- `422`: Validation Error
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-15** `e9fa1fac093b`: 1 info
  - the endpoint scheme security `HTTPBearer` was added to the API

[Operation history](https://skmtc.dev/happenstance/apis/happenstance-api/changes/v1/search/:search_id/get.md)

---

[API](https://skmtc.dev/happenstance/apis/happenstance-api.md) - [All operations](https://skmtc.dev/happenstance/apis/happenstance-api/llms.txt) - [OpenAPI document](https://skmtc.dev/happenstance/apis/happenstance-api/revisions/0b6ee3927db3?raw)