API Reference
Social Research API
The Social Research API searches community platforms — Reddit, HackerNews, and Twitter/X — to surface real-world opinions, discussions, and reactions. Powered by the Social Search backend with HyperFusion ranking optimised for community signal quality.
POST/v1/social
Request
Headers
| Header | Value | Required |
|---|---|---|
Authorization | Bearer hsx_... | Yes |
Content-Type | application/json | Yes |
Body parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query. Max 500 characters. |
platforms | string[] | No | Filter to specific platforms: reddit, hackernews, twitter. Default: all platforms. |
sort | string | No | Sort order: relevance (default), recent, top. |
time_range | string | No | Filter by date: day, week, month, year, all (default). |
max_results | integer | No | Maximum results to return. Range: 1–50. Default: 20. |
include_comments | boolean | No | Include top comments for each post. Default: false. |
min_score | integer | No | Minimum upvote/point score to include. Default: 0. |
subreddits | string[] | No | Restrict Reddit results to specific subreddits. |
Example request
social.sh
curl -X POST https://api.hypersearchx.zuhabul.com/v1/social \
-H "Authorization: Bearer hsx_your_key" \
-H "Content-Type: application/json" \
-d '{
"query": "rust vs go performance 2025",
"platforms": ["reddit", "hackernews"],
"sort": "top",
"time_range": "year",
"max_results": 15,
"include_comments": true
}'social.ts
const res = await fetch("https://api.hypersearchx.zuhabul.com/v1/social", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.HSX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
query: "rust vs go performance 2025",
platforms: ["reddit", "hackernews"],
sort: "top",
time_range: "year",
max_results: 15,
include_comments: true,
}),
});
const data = await res.json();Response
response.json
{
"meta": {
"query": "rust vs go performance 2025",
"platforms_queried": ["reddit", "hackernews"],
"total_results": 15,
"duration_ms": 842
},
"results": [
{
"id": "reddit_abc123",
"platform": "reddit",
"title": "Rust vs Go in 2025 — My experience rewriting a service",
"url": "https://reddit.com/r/rust/comments/abc123/",
"author": "u/rustacean_dev",
"subreddit": "rust",
"score": 1847,
"num_comments": 234,
"created_at": "2025-03-15T14:22:00Z",
"body": "After rewriting our API from Go to Rust, here's what we found...",
"top_comments": [
{
"author": "u/go_gopher",
"body": "Interesting. In my experience Go wins on developer velocity...",
"score": 412
}
],
"relevance_score": 0.94
},
{
"id": "hn_456789",
"platform": "hackernews",
"title": "Ask HN: Rust or Go for systems programming in 2025?",
"url": "https://news.ycombinator.com/item?id=456789",
"author": "thrower42",
"score": 312,
"num_comments": 187,
"created_at": "2025-06-01T09:15:00Z",
"relevance_score": 0.89
}
]
}Response fields
| Field | Type | Description |
|---|---|---|
platform | string | reddit, hackernews, or twitter |
score | integer | Platform-native upvotes/points |
num_comments | integer | Number of comments/replies |
subreddit | string? | Reddit-only: subreddit name |
top_comments | object[]? | Present when include_comments: true |
relevance_score | float | HyperFusion-ranked relevance (0–1) |
CLI equivalent
bash
# Search social platforms via CLI
hsx social reddit "rust performance"
hsx social hackernews "programming languages 2025"
# With options
hsx social reddit "rust" --sort top --time week --min-score 100