Skip to main content
GET
/
v1
/
search
/
{search_id}
Get Search
curl --request GET \
  --url https://api.happenstance.ai/v1/search/{search_id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "<string>",
  "url": "<string>",
  "status": "<string>",
  "text": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "group_ids": [
    "<string>"
  ],
  "include_friends_connections": false,
  "include_my_connections": false,
  "mutuals": [
    {
      "index": 123,
      "id": "<string>",
      "name": "<string>",
      "happenstance_url": "<string>"
    }
  ],
  "traits": [
    {
      "index": 123,
      "header": "<string>",
      "description": "<string>"
    }
  ],
  "results": [
    {
      "id": "<string>",
      "name": "<string>",
      "weighted_traits_score": 123,
      "socials": {
        "happenstance_url": "<string>",
        "linkedin_url": "<string>",
        "twitter_url": "<string>"
      },
      "current_title": "<string>",
      "current_company": "<string>",
      "summary": "<string>",
      "mutuals": [
        {
          "index": 123,
          "affinity_score": 123
        }
      ],
      "traits": [
        {
          "index": 123,
          "score": 123,
          "evidence": "<string>"
        }
      ]
    }
  ],
  "page_id": "<string>",
  "next_page": "<string>",
  "has_more": false
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

search_id
string
required

Query Parameters

page_id
string | null

Response

Successful Response

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
default:false

Whether the search included friends' connections

include_my_connections
boolean
default:false

Whether the search included the user's own connections

mutuals
SearchMutualV1 · object[] | null

All unique mutual connections across results. Results reference these by index.

traits
SearchTraitV1 · object[] | null

All trait definitions for this search. Results reference these by index.

results
SearchPersonV1 · object[] | null

Search results (only populated when status is COMPLETED)

page_id
string | null

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 | null

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
default:false

Whether more results may be available via POST /v1/search/{id}/find-more. Searches return up to 30 results at a time.