Skip to main content
POST
Collect an audience into a dataset

Authorizations

Authorization
string
header
required

A SuperX API key ("sxk_..."), created in the SuperX app under Account > API / MCP / CLI. Keys are server-side secrets.

Headers

Idempotency-Key
string

Unique key (max 64 characters) for safe retries. Replays carry the "Idempotency-Replayed" response header set to "true". Keys are retained for 24 hours.

Maximum string length: 64

Body

application/json
source
enum<string>
required

Who to collect. repliers, quoters and reposters need a post target; list_members needs a public X list; my_posts and my_replies read the account's own synced posts and take no target.

research is different: it reads people's recent posts and writes an outreach brief per person instead of walking an audience. It takes exactly ONE of handles, list_id, agent_id or dataset_id, plus focus and a max_rows of 1-25 (default 10), and ignores target and filters.

Available options:
repliers,
quoters,
reposters,
list_members,
my_replies,
my_posts,
research
target
string

An x.com post URL or numeric post id, or for list_members an x.com list URL (/i/lists/) or numeric list id. Omit for my_posts and my_replies.

title
string

Title for the dataset. A sensible one is generated when omitted.

Maximum string length: 120
max_rows
integer
default:500

Rows to collect at most. For source: "research" the range is 1-25 and the default is 10 (one profile per row).

Required range: 1 <= x <= 1000
account_id
string

Which of your accounts to collect as. Omit for the main account.

handles
string[]

research only: research these X handles (with or without the @). Exactly one source field.

Maximum array length: 25
list_id
string

research only: research the members of this contact list. Exactly one source field.

agent_id
integer

research only: research this signal agent's leads. Exactly one source field.

Required range: x >= 1
dataset_id
string

research only: research the people in this dataset. Exactly one source field.

focus
string

research only: an optional steer, e.g. "founders who might need audience-growth tooling".

Maximum string length: 300
filters
object

Response

The collection finished inside the request. data is null when nothing matched, with a note explaining why. A research run adds meta (what was requested, what was researched, what it cost) and the X-Credits-* headers.

data
object | null
meta
object

Research runs only. Absent on audience collections.

note
string

Present when something needs saying, such as an empty result or ignored filters.