---
title: "Submit search"
method: POST
path: "/api/v1/search"
tags: ["Search"]
---

# Submit search

`POST /api/v1/search`

Run a search across supported web and social sources. The default response returns an operation to poll; add sync=true only when you want to wait briefly for an immediate result.

## Query parameters

- `sync` boolean

## Headers

- `Idempotency-Key` string

## Request body

- PostSearchDto
  - `type` 'web_search' | 'site_search' | 'linkedin_keyword' | 'x_keyword' | 'reddit_search' | 'tiktok_keyword' | 'tiktok_hashtag', required — Type of search to perform
  - `query` string — Search query string. Required unless match_any/match_all are provided.
  - `match_any` string[] — Keywords where ANY must match (OR logic). Used to build search query.
  - `match_all` string[] — Keywords where ALL must match (AND logic). Used to build search query.
  - `exclude` string[] — Keywords to exclude from results.
  - `max_results` number — Maximum results to return (default 10, max 50)
  - `site` string — Domain to restrict search to (required for site_search)
  - `include_domains` string[] — Domains to include results from (web_search only)
  - `exclude_domains` string[] — Domains to exclude results from (web_search only)
  - `sort_by` 'relevance' | 'recent' — Sort by relevance or recency for supported keyword searches. Reddit maps recent to Reddit's new sort.
  - `match_mode` 'exact' | 'broad' — Match mode for LinkedIn keyword searches. exact searches the query as a quoted phrase; broad sends the query without phrase quotes.
  - `date_filter` string — Date filter for LinkedIn search (e.g. past-24h, past-week)
  - `hashtag` string — Hashtag to search for (required for tiktok_hashtag type, without # prefix)
  - `subreddit` string — Subreddit to search within (reddit_search only)

## Response `200`

Search completed immediately.

- SearchResultDto
  - `id` string, required — Unique search result ID
  - `status` 'queued' | 'processing' | 'succeeded' | 'failed', required — Current status
  - `type` 'web_search' | 'site_search' | 'linkedin_keyword' | 'x_keyword' | 'reddit_search' | 'tiktok_keyword' | 'tiktok_hashtag', required — Search type
  - `query` string, required — Original query
  - `poll_url` string — URL to poll for result
  - `results` SearchResultItemDto[], nullable — Search results array
    - `url` string, required — Result URL
    - `title` string, required — Result title
    - `content` string, nullable — Content snippet or post text
    - `published_at` string, nullable — Published date (ISO)
    - `author_name` string, nullable — Author name (LinkedIn)
    - `author_headline` string, nullable — Author headline (LinkedIn)
    - `id` string, nullable — Source-native stable entity ID, when available
    - `platform_video_id` string, nullable — Source-native stable post/video/activity ID, when available
    - `post_url` string, nullable — Source-native canonical post URL, when available
    - `author_username` string, nullable — Author handle or username, when available
  - `total_results` number, nullable — Total results found
  - `error` SearchErrorDto
    - `message` string, required — Safe error message
    - `retryable` boolean, required — Whether retrying the search may succeed
  - `created_at` string, required — ISO timestamp of creation
  - `completed_at` string, nullable — ISO timestamp of completion

## Other responses

- `202` — Search accepted. Poll the returned URL for status and results.
- `400` — The request body or parameters are invalid.
- `401` — Authentication is required.
- `402` — The organization does not have enough credits for this request.
- `422` — The request body is invalid.
- `500` — An unexpected error occurred.

---

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