Jump to endpoint

API reference

Every endpoint, what it costs, and a curl you can paste. Machine-readable: llms.txt · openapi.json · llms-full.txt.

Quickstart

Two calls to get a key, then one to use it. The whole thing works from a terminal, so an agent can drive it while you read the code out of your own inbox.

curl -X POST -H "Content-Type: application/json" \
  "https://api.socialsearchapi.com/v1/auth/request-code" -d '{"email":"[email protected]"}'

# ...read the 6-digit code from your email...

curl -X POST -H "Content-Type: application/json" \
  "https://api.socialsearchapi.com/v1/auth/verify" -d '{"email":"[email protected]","otp":"123456"}'

That returns a trial_key good for 5 calls on any platform. Export it and go:

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/hackernews/search?query=llm+agents"

It comes back like this (real response, captured 2026-07-25):

{
  "success": true,
  "platform": "hackernews",
  "data": {
    "total": 16736,
    "items": [
      {
        "id": "46990729",
        "platform": "hackernews",
        "type": "post",
        "title": "An AI agent published a hit piece on me",
        "text": "Previously: AI agent opens a PR write a blogpost to shames the maintainer who closes it - https://news.ycombinator.co...",
        "url": "https://theshamblog.com/an-ai-agent-published-a-hit-piece-on-me/",
        "author": "scottshambaugh",
        "created_at": "2026-02-12T16:23:24Z",
        "metrics": {
          "comments": 951,
          "score": 2346
        },
        "extra": {
          "hn_url": "https://news.ycombinator.com/item?id=46990729",
          "created_at_raw": "2026-02-12T16:23:24Z"
        }
      }
    ]
  },
  "credits_used": 1
}

That's the whole interface. Change hackernews to reddit, x, tiktok — same envelope, same item fields, different platform. Get a key — email and a 6-digit code, 5 free calls, no card.

Authentication

Send your key in the x-api-key header on every request. There is no anonymous access — a call without a key is a 401. All examples below assume export SS_KEY=your_key.

export SS_KEY=ss_live_...
curl -H "x-api-key: $SS_KEY" "https://api.socialsearchapi.com/v1/reddit/search?query=llm+agents"

Two kinds of key

kind	what it is
trial	Issued the first time an email is verified. 5 calls, any endpoint, no credits. Deliberately disposable — it is revoked automatically when the account first pays, so it is safe for an agent to hold in a terminal or a log.
live	Issued on payment. One per account, rotatable. Never returned by this API and never emailed — it is shown only in the dashboard, so it cannot leak into an agent's context. See /v1/keys/current.

Agents: mint yourself a trial key with the two calls in the Quickstart. When your user needs their permanent key, call POST /v1/auth/browser-link and open the returned dashboard_url in their browser — it signs them in and shows the key so they can paste it into .env themselves. Never ask a user to paste a live key back to you.

Response schema

Every list endpoint returns the same envelope. Items always carry text or title, url, author and created_at, plus that platform's own metrics. When a fallback provider serves the call, served_by names it.

{
  "success": true,
  "platform": "reddit",
  "served_by": "native",
  "data": {
    "total": 3,
    "items": [
      {
        "platform": "reddit",
        "type": "post",
        "title": "I tested every free LLM provider for AI agents. Here's the only 3 worth using.",
        "url": "https://old.reddit.com/r/better_claw/comments/1tjuuem/i_tested_every_free_llm_provider_for_ai_agents/",
        "author": "ShabzSparq",
        "created_at": "2026-05-21T19:17:20Z",
        "metrics": {
          "comments": 63,
          "score": 180
        },
        "extra": {
          "url_path": "/r/better_claw/comments/1tjuuem/i_tested_every_free_llm_provider_for_ai_agents/",
          "subreddit": "r/better_claw",
          "created_at_raw": "2026-05-21T19:17:20+00:00"
        }
      }
    ]
  },
  "credits_used": 1
}

Errors

Errors use one shape too, and carry a fix field written for whoever — or whatever — is reading it.

{
  "success": false,
  "endpoint": "/v1/x/search",
  "error": {
    "type": "INSUFFICIENT_CREDITS",
    "status": 402,
    "message": "Not enough credits for this call.",
    "fix": "Top up at https://socialsearchapi.com/dashboard",
    "docs_url": "https://socialsearchapi.com/docs#errors"
  },
  "credits_used": 0,
  "request_id": "req-..."
}

status	error.type	what to do
401	UNAUTHORIZED	Missing, unknown, rotated or revoked key. There is no anonymous tier. Note a trial key is revoked when the account converts to paid.
402	INSUFFICIENT_CREDITS	Balance is too low for this endpoint's cost. Top up; nothing is queued and nothing is deleted.
402	TRIAL_EXHAUSTED	This email's 5 trial calls are used up. Buy credits — the live key appears in the dashboard.
400	BAD_REQUEST	The request was understood but rejected — the message says why.
422	—	A required parameter is missing or the wrong type. FastAPI's body names the field.
424	ALL_SOURCES_FAILED / UPSTREAM_ERROR	Every provider for that platform failed. You are not charged. Retry, or use another platform.
503	SOURCE_BLOCKED	The source is temporarily blocking us. You are not charged. Retry shortly — retries usually clear it.
501	NOT_CONFIGURED	That upstream isn't configured on this deployment. Tell us at [email protected].

Credits & limits

Every endpoint card below shows its cost. Credits are deducted on success only — a failed call, including one where we burned a fallback attempt, costs you nothing. A trial key is metered in calls instead: 5 successful calls total, any endpoint. Rate limit is 20 requests per second per key. Full price table on the pricing page.

Platforms

GET/v1/reddit/search1 credit · trial ok

Full-text search across Reddit. Primary path is a native old.reddit scrape over a residential proxy; if it is blocked or empty we fail over to a backup provider automatically and `served_by` names whichever one answered.

param	type
query*	string
limit	integer = 25
sort	string = relevance
t	string = all

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/reddit/search?query=llm+agents"

GET/v1/reddit/subreddit/search1 credit · trial ok

Same as Reddit search, scoped to a single subreddit.

param	type
query*	string
subreddit*	string
limit	integer = 25
sort	string = relevance
t	string = all

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/reddit/subreddit/search?subreddit=programming&query=llm+agents"

GET/v1/reddit/omni-search5 credits · trial ok

Returns matching threads plus their top comments in one call, so an agent gets the discussion rather than just the titles.

param	type
query*	string
comments	integer = 8
sort	string = relevance
t	string = all
threads	integer = 8

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/reddit/omni-search?query=llm+agents"

X / Twitter

GET/v1/x/search5 credits · trial ok

Full-text tweet search with engagement metrics and author follower counts.

param	type
query*	string
query_type	string = Latest

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/x/search?query=llm+agents"

GET/v1/x/user-tweets5 credits · trial ok

Latest tweets for one handle, newest first.

param	type
username*	string
include_replies	boolean = False

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/x/user-tweets?username=nasa"

Instagram

GET/v1/instagram/user-posts3 credits · trial ok

Recent posts for a public Instagram handle, with caption, likes, comments and view counts.

param	type
handle*	string

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/instagram/user-posts?handle=nasa"

GET/v1/instagram/profile3 credits · trial ok

Profile metadata for a public Instagram handle.

param	type
handle*	string

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/instagram/profile?handle=nasa"

GET/v1/instagram/search-profiles3 credits · trial ok

Find public profiles by name or keyword. Instagram removed public hashtag search, so profile lookup is the supported entry point.

param	type
query*	string

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/instagram/search-profiles?query=llm+agents"

TikTok

GET/v1/tiktok/user-videos3 credits · trial ok

Recent videos for a TikTok handle, with play, like, comment and share counts.

param	type
handle*	string

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/tiktok/user-videos?handle=nasa"

GET/v1/tiktok/hashtag3 credits · trial ok

Videos carrying a given hashtag.

param	type
hashtag*	string

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/tiktok/hashtag?hashtag=ai"

GET/v1/tiktok/profile3 credits · trial ok

Profile metadata for a TikTok handle.

param	type
handle*	string

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/tiktok/profile?handle=nasa"

Facebook

GET/v1/facebook/page-posts3 credits · trial ok

Recent posts from a public Facebook Page URL, with reaction and comment counts.

param	type
url*	string

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/facebook/page-posts?url=https%3A%2F%2Fwww.facebook.com%2Fnasa"

GET/v1/facebook/profile3 credits · trial ok

Page metadata for a public Facebook URL.

param	type
url*	string

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/facebook/profile?url=https%3A%2F%2Fwww.facebook.com%2Fnasa"

Hacker News

GET/v1/hackernews/search1 credit · trial ok

Full-text search over Hacker News via the official Algolia index.

param	type
query*	string
hitsPerPage	integer = 30
sort	string = relevance
tags	string = story

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/hackernews/search?query=llm+agents"

YouTube

GET/v1/youtube/search1 credit · trial ok

Video search with channel, duration and view count. No Google API quota is consumed.

param	type
query*	string
limit	integer = 20

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/youtube/search?query=llm+agents"

Bluesky

GET/v1/bluesky/search-actors1 credit · trial ok

Find Bluesky accounts by name or handle.

param	type
query*	string
limit	integer = 15

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/bluesky/search-actors?query=llm+agents"

GET/v1/bluesky/author-feed1 credit · trial ok

param	type
actor*	string
limit	integer = 25

Mastodon

GET/v1/mastodon/tag1 credit · trial ok

Public timeline for one hashtag. `instance` must be a public Mastodon hostname (validated before any request is made).

param	type
tag*	string
instance	string = mastodon.social
limit	integer = 25

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/mastodon/tag?tag=ai"

GET/v1/mastodon/search1 credit · trial ok

Search public Mastodon posts.

param	type
query*	string
limit	integer = 25

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/mastodon/search?query=llm+agents"

App Store

GET/v1/appstore/search1 credit · trial ok

App search through the official iTunes endpoint, with rating and price.

param	type
query*	string
country	string = us
limit	integer = 20

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/appstore/search?query=llm+agents"

GET/v1/appstore/reviews1 credit · trial ok

Customer reviews for one iOS app, by country.

param	type
app_id*	string
country	string = us
page	integer = 1

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/appstore/reviews?app_id=310633997"

Google Play

GET/v1/gplay/search2 credits · trial ok

Google Play app search with rating and install band.

param	type
query*	string
country	string = us
limit	integer = 10

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/gplay/search?query=llm+agents"

GET/v1/gplay/details1 credit · trial ok

Full listing detail for one Android app id.

param	type
app_id*	string
country	string = us

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/gplay/details?app_id=com.whatsapp"

Web & News

GET/v1/google_news/search1 credit · trial ok

GitHub

GET/v1/github/search1 credit · trial ok

GitHub search across repositories, code, issues or users.

param	type
query*	string
kind	string = repositories
per_page	integer = 20
sort	string

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/github/search?query=llm+agents"

Cross-platform

GET/v1/search/forums10 credits · trial ok

One query, both forums, merged into a single ranked list in the shared item schema. Pricing is honest about partial results: if a source fails you are charged pro-rata for the sources that answered (the `sources` block in the response shows exactly which), and a response where every source failed costs nothing.

param	type
query*	string
comments	integer = 6
threads	integer = 6

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/search/forums?query=llm+agents"

GET/v1/search/everywhere20 credits · trial ok

Fans the query out across every live platform and merges the results. Costs more because it is many upstream calls in one request — and only for what serves: partial responses are charged pro-rata for the sources that answered (`sources` in the response), and a total failure costs nothing.

param	type
query*	string

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/search/everywhere?query=llm+agents"

Account & billing

Account

GET/v1/credits/balance1 credit · trial ok

Just the balance, for a cheap pre-flight check.

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/credits/balance"

POST/v1/auth/request-code1 credit · trial ok

Step 1 of sign-in. Same call whether the address is new or returning — there is no separate signup. Works from a web form or from a terminal, so an agent can drive it while the user reads the code out of their own inbox.

param	type
email*	string	in the JSON body
agent	string	in the JSON body

curl -X POST -H "Content-Type: application/json" \
  "https://api.socialsearchapi.com/v1/auth/request-code" \
  -d '{"email": "[email protected]"}'

POST/v1/auth/verify1 credit · trial ok

Step 2. Returns a disposable trial key (safe for an agent to hold) and a single-use `dashboard_url`. The live key is never in this response.

param	type
email*	string	in the JSON body
otp*	string	in the JSON body

curl -X POST -H "Content-Type: application/json" \
  "https://api.socialsearchapi.com/v1/auth/verify" \
  -d '{"email": "[email protected]", "otp": "123456"}'

POST/v1/auth/session1 credit · trial ok

Called by the dashboard when it loads with ?s=<magic>. Burns the single-use token and returns a session token.

param	type
magic*	string	in the JSON body

curl -X POST -H "Content-Type: application/json" \
  "https://api.socialsearchapi.com/v1/auth/session" \
  -d '{"magic": "..."}'

POST/v1/auth/browser-link1 credit · trial ok

Authenticated with any of the caller's own API keys. Lets an agent open an authenticated dashboard tab for its user without ever handling the live key itself.

curl -X POST -H "Content-Type: application/json" \
  "https://api.socialsearchapi.com/v1/auth/browser-link" \
  -d '{}'

GET/v1/keys/current1 credit · trial ok

Requires an x-session header from /v1/auth/session. Deliberately NOT reachable with an API key, so a terminal agent cannot read it. Keys are hashed at rest: the plaintext is returned exactly once — on the first visit after paying, or right after a rotate.

param	type
x-session	string

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/keys/current"

POST/v1/keys/rotate1 credit · trial ok

Rotate the live key (browser session only)

param	type
x-session	string

curl -X POST -H "x-api-key: $SS_KEY" -H "Content-Type: application/json" \
  "https://api.socialsearchapi.com/v1/keys/rotate" \
  -d '{}'

GET/v1/me1 credit · trial ok

Balance and usage for the calling key — or for the signed-in browser session (x-session). Never returns the key itself.

param	type
x-session	string

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/me"

Billing

GET/v1/plans1 credit · trial ok

Available credit packs, the exact per-credit rate of each, and the discount against list.

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/plans"

POST/v1/checkout1 credit · trial ok

Works with any of the caller's API keys, or with a browser session — live keys are show-once, so the dashboard pays via its session.

param	type
x-session	string
credits	integer	in the JSON body
plan	string	in the JSON body

curl -X POST -H "x-api-key: $SS_KEY" -H "Content-Type: application/json" \
  "https://api.socialsearchapi.com/v1/checkout" \
  -d '{"credits": 25000}'

POST/v1/checkout/confirm1 credit · trial ok

Called by the /pay/success page when the buyer returns from PayPal. Safe to repeat: fulfillment is exactly-once. The webhook and a server-side reconciliation loop are the backups, so credits arrive even if the browser never comes back.

param	type
order_id*	string	in the JSON body

curl -X POST -H "x-api-key: $SS_KEY" -H "Content-Type: application/json" \
  "https://api.socialsearchapi.com/v1/checkout/confirm" \
  -d '{"order_id": "..."}'

Status

GET/v1/status1 credit · trial ok

Liveness plus which upstream providers are configured. Unauthenticated.

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/status"