Skip to main content
POST
/
api
/
v1
/
search
Submit search
curl --request POST \
  --url https://developer.thehog.ai/api/v1/search \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: <api-key>' \
  --header 'X-Secret-Key: <api-key>' \
  --data '
{
  "type": "web_search",
  "query": "AI startup funding 2026",
  "match_any": [
    "AI startup",
    "machine learning funding"
  ],
  "match_all": [
    "Series A",
    "2026"
  ],
  "exclude": [
    "crypto",
    "blockchain"
  ],
  "max_results": 10,
  "site": "techcrunch.com",
  "include_domains": [
    "<string>"
  ],
  "exclude_domains": [
    "<string>"
  ],
  "sort_by": "relevance",
  "match_mode": "exact",
  "date_filter": "<string>",
  "hashtag": "productanalytics",
  "subreddit": "startups"
}
'
{
  "id": "<string>",
  "query": "<string>",
  "created_at": "<string>",
  "poll_url": "<string>",
  "results": [
    {
      "url": "<string>",
      "title": "<string>",
      "content": "<string>",
      "published_at": "<string>",
      "author_name": "<string>",
      "author_headline": "<string>",
      "id": "<string>",
      "platform_video_id": "<string>",
      "post_url": "<string>",
      "author_username": "<string>"
    }
  ],
  "total_results": 123,
  "error": {
    "message": "<string>",
    "retryable": true
  },
  "completed_at": "<string>"
}

​
POST /api/v1/search

Submit a search across web, LinkedIn, X, Reddit, or TikTok. Returns 202.
Submit a search query across one or more platforms. Returns 202 Accepted with a poll URL. For Reddit post search, set type to reddit_search. Use sort_by: "relevance" for Reddit’s relevance ranking or sort_by: "recent" for Reddit’s newest-post ranking.

​
Example

curl -X POST https://developer.thehog.ai/api/v1/search \
  -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"type": "web_search", "query": "AI CRM tools", "max_results": 10}'

Authorizations

​
X-Access-Key
string
header
required

The public API key from the Credentials page.

​
X-Secret-Key
string
header
required

The API secret shown when the credential is created.

Headers

​
Idempotency-Key
string

Prevents duplicate work if you retry the same request with the same key.

Query Parameters

​
sync
boolean

Set to true to wait briefly for a completed result instead of immediately returning an operation to poll.

Body

application/json
​
type
enum<string>
required

Type of search to perform

Available options:
web_search,
site_search,
linkedin_keyword,
x_keyword,
reddit_search,
tiktok_keyword,
tiktok_hashtag
Example:

"web_search"

​
query
string

Search query string. Required unless match_any/match_all are provided.

Example:

"AI startup funding 2026"

​
match_any
string[]

Keywords where ANY must match (OR logic). Used to build search query.

Example:
["AI startup", "machine learning funding"]
​
match_all
string[]

Keywords where ALL must match (AND logic). Used to build search query.

Example:
["Series A", "2026"]
​
exclude
string[]

Keywords to exclude from results.

Example:
["crypto", "blockchain"]
​
max_results
number
default:10

Maximum results to return (default 10, max 50)

​
site
string

Domain to restrict search to (required for site_search)

Example:

"techcrunch.com"

​
include_domains
string[]

Domains to include results from (web_search only)

​
exclude_domains
string[]

Domains to exclude results from (web_search only)

​
sort_by
enum<string>
default:relevance

Sort by relevance or recency for supported keyword searches. Reddit maps recent to Reddit's new sort.

Available options:
relevance,
recent
​
match_mode
enum<string>
default:exact

Match mode for LinkedIn keyword searches. exact searches the query as a quoted phrase; broad sends the query without phrase quotes.

Available options:
exact,
broad
​
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)

Example:

"productanalytics"

​
subreddit
string

Subreddit to search within (reddit_search only)

Example:

"startups"

Response

Search completed immediately.

​
id
string
required

Unique search result ID

​
status
enum<string>
required

Current status

Available options:
queued,
processing,
succeeded,
failed
​
type
enum<string>
required

Search type

Available options:
web_search,
site_search,
linkedin_keyword,
x_keyword,
reddit_search,
tiktok_keyword,
tiktok_hashtag
​
query
string
required

Original query

​
created_at
string
required

ISO timestamp of creation

​
poll_url
string

URL to poll for result

​
results
object[] | null

Search results array

​
total_results
number | null

Total results found

​
error
object

Error details when failed

​
completed_at
string | null

ISO timestamp of completion