Media and social · twitterapi.io + Reddit

social.search

Searches X posts or profiles (paid, per tweet) or Reddit posts/subreddits (free). details returns the full post with engagement, or the profile.

Operation: POST /v1/capabilities/social.search/execute
operationId: executeSocialSearch
Typical credits: 2
Search deadline: 15 s server-side
Paging: token
Availability: ConfiguredChecked 2026-09-23 21:02 UTC

Cost basis: X: $0.00015 per tweet returned. Reddit: free. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request

Body of POST /v1/capabilities/social.search/execute, JSON, validated against the SocialSearchRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of social.search
Field	Type	Required	Default	Constraints and description
platform	"x" \| "reddit"	yes
query	string	yes		min length 1, max length 300
kind	"posts" \| "profiles"	no	"posts"
num	integer	no	10	min 1, max 25 Results per page (1-25).

Unknown keys are rejected with 400 invalid_request.

Examples

X posts

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/social.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"platform":"x","query":"fastify","kind":"posts","num":10}'

Reddit posts

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/social.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"platform":"reddit","query":"fastify vs express","num":10}'

No recorded response is published for this capability yet. The envelope is the ExecuteResponse component (see sessions and records); the record keys below are what the adapter emits. A first call with the example above returns search_id, the records and the charge.

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the SocialSearchRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Record keys of social.search
Key	Type	Presence	Note
platform	"x" \| "reddit"	always
kind	"post" \| "profile"	always
author	string	when the source has it
author_name	string	when the source has it
created_at	string	when the source has it
likes	integer	when the source has it
reposts	integer	when the source has it
replies	integer	when the source has it
views	integer	when the source has it
followers	integer	when the source has it	Profiles.
following	integer	when the source has it	Profiles.
posts	integer	when the source has it	Profiles.
verified	boolean	when the source has it	Profiles.
location	string	when the source has it	Profiles.
subreddit	string	when the source has it	Reddit.
score	integer	when the source has it	Reddit.
comments	integer	when the source has it	Reddit.
link_url	string	when the source has it	Reddit.
subscribers	integer	when the source has it	Reddit.
karma	integer	when the source has it	Reddit.

Caveats

Reddit refuses requests from some datacenter networks; that surfaces as provider_error.

Follow-ups

Paging: Provider cursor; more fetches the next page from the source. Send { "search_id": "…", "action": "more" } while has_more is true; tolerate an empty page and stop after a bounded number of pages.
Update: Re-run with changed parameters (merged into the stored query); page state resets, search_id stays. Params accept any subset of the request fields (SocialSearchUpdateParams).
Record actions:
- details: Full post with engagement counts, or full profile.
Detail behaviour: Free provider lookup on first call; repeats are cached. details re-reads the post or profile; X items are billed per tweet, Reddit is free.

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

Record detail objects of this capability are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/social.search/execute", {
  body: {
    "platform": "x",
    "query": "fastify",
    "kind": "posts",
    "num": 10
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);