---
title: "Create Search"
method: POST
path: "/v1/search"
---

# Create Search

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

## Request body

- SearchRequestV1
  - `text` string, required — Search query text. Use @mentions to filter results to a specific person's connections (e.g., 'engineers @Jane Smith knows').
  - `group_ids` string[], nullable — List of group IDs to search within.
  - `include_friends_connections` boolean — Search across your friends' connections
  - `include_my_connections` boolean — Search across your own connections
  - `search_everyone` boolean

## Response `200`

Successful Response

- CreateSearchResponseV1 — Response from POST /v1/search - creating a new search request.
  - `id` string, required — Unique identifier for the search request
  - `url` string, required — URL to view the search results on Happenstance
  - `warning` string, nullable — Warning message when credit balance is low

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

---

[API](https://skmtc.net/happenstance/apis/happenstance-api.md) · [All operations](https://skmtc.net/happenstance/apis/happenstance-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/happenstance/happenstance-api/revisions/d5e1f45dc5e4/schema)