Collect the repliers, quote posters or reposters of a post, the
members of a public X list, or the account’s own posts or replies,
into a stored dataset you can then read, export, or copy into a
contact list.
source: "research" is the exception: instead of walking an audience
it reads people’s recent posts and writes a short outreach brief for
each one (what they do, what they are building, recent topics,
personalization hooks that QUOTE their real posts, and an opener
angle). Give it exactly one source - handles, list_id, agent_id
or dataset_id - plus optional focus, title and max_rows (1-25,
default 10). The briefs land as an ordinary dataset, so
GET /v1/datasets/{id}/rows, /export and /contacts read them
unchanged. More than 5 profiles research in the background and answer
202. If none of them could be researched, the answer is 200 with
data: null, the reasons in meta.skipped, and every credit
returned.
This endpoint can answer before the work is finished. A small
collection runs inside the request and answers 200 with a ready
dataset. A big one, or one whose size cannot be established up
front, answers 202 with a collecting dataset: poll
GET /v1/datasets/{id} until status is ready (or failed) before
reading its rows. Only one background collection runs per account at a
time; a second one gets 409 collection_in_progress.
If nothing matched the filters, the response is 200 with
data: null and a note: no dataset is created for an empty result,
and the daily collection slot is given back.
my_posts and my_replies read the account’s own synced posts: they
take no target, always finish inside the request, and ignore the
profile filters (the response note says so rather than dropping them
silently).
Cost. Every collection counts against a limit of 10 per day for
the account, shared with the collections Ask SuperX runs in the app
(429 collection_quota_exceeded). Collections that read X also spend
the enrichment allowance: one unit for the size estimate, plus the
pages the walk is expected to need, all charged before the walk
starts so X-RateLimit-Remaining stays honest about work that
outlives the response. Own-content collections spend nothing.
Research is charged in AI credits, not collections.source: "research" costs a flat 1 credit per profile ACTUALLY
researched: profiles that could not be researched come back in
meta.skipped and their credits are returned. It spends one of the
plan’s daily profile-research runs (429 ai_action_limited with
scope: "account") and a slice of a platform-wide fair-use ceiling on
live-data actions shared by every SuperX account
(429 ai_action_limited with scope: "platform"), and it does NOT
count against the 10 collections a day. An empty credit pool is
429 ai_credits_exhausted. What was charged comes back in
meta.credits_charged and in the X-Credits-* headers on the 200;
a background research run settles when it finishes, so its 202
carries neither, and the figure lands on GET /v1/me and your ledger.
Datasets created here appear alongside the ones Ask SuperX built, and
are kept for 30 days.
Send an Idempotency-Key header to make retries safe: the same key
with the same body replays the first response with
Idempotency-Replayed: true, and the same key with a different body
is rejected with 409 idempotency_key_reuse.
Unique key (max 64 characters) for safe retries. Replays carry the "Idempotency-Replayed" response header set to "true". Keys are retained for 24 hours.
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.
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.
Present when something needs saying, such as an empty result or ignored filters.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"SuperX","colors":{"primary":"#F4503B","light":"#FB7359","dark":"#D93820"},"logo":{"light":"https://mintcdn.com/superx/ZOrKRYsYXbBhitoI/logo/light.svg?fit=max\u0026auto=format\u0026n=ZOrKRYsYXbBhitoI\u0026q=85\u0026s=d465c38938c34f6ab75cfc50d0039be2","dark":"https://mintcdn.com/superx/ZOrKRYsYXbBhitoI/logo/dark.svg?fit=max\u0026auto=format\u0026n=ZOrKRYsYXbBhitoI\u0026q=85\u0026s=b717e05282be47857b4c42e3c9f28b15"},"favicon":"https://mintcdn.com/superx/ZOrKRYsYXbBhitoI/favicon.png?fit=max\u0026auto=format\u0026n=ZOrKRYsYXbBhitoI\u0026q=85\u0026s=05aaa6612cdd959e0edb14d963806660","appearance":{"default":"system"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"superx","hasAudioNarration":false,"actualSubdomain":"superx","customDomains":["docs.superx.so"],"gitSource":{"type":"github","owner":"superx-so","repo":"superx-docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"chroma":{"latestBuiltDeploymentHistoryId":"6ac68ff611e54a617d7548d2","collectionId":"371386e6-3679-44e4-aa28-f1b7adee5865","liveDeploymentHistoryId":"6ac68ff611e54a617d7548d2","schemaVersion":"v3"},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6ac68ff611e54a617d7548d2","clientVersion":"0.0.4067","searchFilterCounts":[{"language":"default","tag":"API Reference","count":106},{"language":"default","tag":"Signals","count":12},{"language":"default","tag":"Documentation","count":10},{"language":"default","tag":"Articles","count":10},{"language":"default","tag":"Scheduling","count":10},{"language":"default","tag":"Audience","count":9},{"language":"default","tag":"Contact Lists","count":9},{"language":"default","tag":"Datasets","count":8},{"language":"default","tag":"Context","count":7},{"language":"default","tag":"Engage","count":7}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/datasets/collect-an-audience-into-a-dataset","slug":"/api-reference/datasets/collect-an-audience-into-a-dataset","pageMetadata":{"title":"Collect an audience into a dataset","description":"Collect the repliers, quote posters or reposters of a post, the\nmembers of a public X list, or the account's own posts or replies,\ninto a stored dataset you can then read, export, or copy into a\ncontact list.\n\n`source: \"research\"` is the exception: instead of walking an audience\nit reads people's recent posts and writes a short outreach brief for\neach one (what they do, what they are building, recent topics,\npersonalization hooks that QUOTE their real posts, and an opener\nangle). Give it exactly one source - `handles`, `list_id`, `agent_id`\nor `dataset_id` - plus optional `focus`, `title` and `max_rows` (1-25,\ndefault 10). The briefs land as an ordinary dataset, so\n`GET /v1/datasets/{id}/rows`, `/export` and `/contacts` read them\nunchanged. More than 5 profiles research in the background and answer\n`202`. If none of them could be researched, the answer is `200` with\n`data: null`, the reasons in `meta.skipped`, and every credit\nreturned.\n\n**This endpoint can answer before the work is finished.** A small\ncollection runs inside the request and answers `200` with a `ready`\ndataset. A big one, **or one whose size cannot be established up\nfront**, answers `202` with a `collecting` dataset: poll\n`GET /v1/datasets/{id}` until `status` is `ready` (or `failed`) before\nreading its rows. Only one background collection runs per account at a\ntime; a second one gets `409 collection_in_progress`.\n\nIf nothing matched the filters, the response is `200` with\n`data: null` and a `note`: no dataset is created for an empty result,\nand the daily collection slot is given back.\n\n`my_posts` and `my_replies` read the account's own synced posts: they\ntake no `target`, always finish inside the request, and ignore the\nprofile filters (the response `note` says so rather than dropping them\nsilently).\n\n**Cost.** Every collection counts against a limit of 10 per day for\nthe account, shared with the collections Ask SuperX runs in the app\n(`429 collection_quota_exceeded`). Collections that read X also spend\nthe enrichment allowance: one unit for the size estimate, plus the\npages the walk is expected to need, all charged before the walk\nstarts so `X-RateLimit-Remaining` stays honest about work that\noutlives the response. Own-content collections spend nothing.\n\n**Research is charged in AI credits, not collections.**\n`source: \"research\"` costs a flat 1 credit per profile ACTUALLY\nresearched: profiles that could not be researched come back in\n`meta.skipped` and their credits are returned. It spends one of the\nplan's daily profile-research runs (`429 ai_action_limited` with\n`scope: \"account\"`) and a slice of a platform-wide fair-use ceiling on\nlive-data actions shared by every SuperX account\n(`429 ai_action_limited` with `scope: \"platform\"`), and it does NOT\ncount against the 10 collections a day. An empty credit pool is\n`429 ai_credits_exhausted`. What was charged comes back in\n`meta.credits_charged` and in the `X-Credits-*` headers on the `200`;\na background research run settles when it finishes, so its `202`\ncarries neither, and the figure lands on `GET /v1/me` and your ledger.\n\nDatasets created here appear alongside the ones Ask SuperX built, and\nare kept for 30 days.\n\nSend an `Idempotency-Key` header to make retries safe: the same key\nwith the same body replays the first response with\n`Idempotency-Replayed: true`, and the same key with a different body\nis rejected with `409 idempotency_key_reuse`.\n","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/datasets","href":"/api-reference/datasets/collect-an-audience-into-a-dataset","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n strong: \"strong\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Collect the repliers, quote posters or reposters of a post, the\\nmembers of a public X list, or the account’s own posts or replies,\\ninto a stored dataset you can then read, export, or copy into a\\ncontact list.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"source: \\\"research\\\"\"\n }), \" is the exception: instead of walking an audience\\nit reads people’s recent posts and writes a short outreach brief for\\neach one (what they do, what they are building, recent topics,\\npersonalization hooks that QUOTE their real posts, and an opener\\nangle). Give it exactly one source - \", _jsx(_components.code, {\n children: \"handles\"\n }), \", \", _jsx(_components.code, {\n children: \"list_id\"\n }), \", \", _jsx(_components.code, {\n children: \"agent_id\"\n }), \"\\nor \", _jsx(_components.code, {\n children: \"dataset_id\"\n }), \" - plus optional \", _jsx(_components.code, {\n children: \"focus\"\n }), \", \", _jsx(_components.code, {\n children: \"title\"\n }), \" and \", _jsx(_components.code, {\n children: \"max_rows\"\n }), \" (1-25,\\ndefault 10). The briefs land as an ordinary dataset, so\\n\", _jsx(_components.code, {\n children: \"GET /v1/datasets/{id}/rows\"\n }), \", \", _jsx(_components.code, {\n children: \"/export\"\n }), \" and \", _jsx(_components.code, {\n children: \"/contacts\"\n }), \" read them\\nunchanged. More than 5 profiles research in the background and answer\\n\", _jsx(_components.code, {\n children: \"202\"\n }), \". If none of them could be researched, the answer is \", _jsx(_components.code, {\n children: \"200\"\n }), \" with\\n\", _jsx(_components.code, {\n children: \"data: null\"\n }), \", the reasons in \", _jsx(_components.code, {\n children: \"meta.skipped\"\n }), \", and every credit\\nreturned.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"This endpoint can answer before the work is finished.\"\n }), \" A small\\ncollection runs inside the request and answers \", _jsx(_components.code, {\n children: \"200\"\n }), \" with a \", _jsx(_components.code, {\n children: \"ready\"\n }), \"\\ndataset. A big one, \", _jsx(_components.strong, {\n children: \"or one whose size cannot be established up\\nfront\"\n }), \", answers \", _jsx(_components.code, {\n children: \"202\"\n }), \" with a \", _jsx(_components.code, {\n children: \"collecting\"\n }), \" dataset: poll\\n\", _jsx(_components.code, {\n children: \"GET /v1/datasets/{id}\"\n }), \" until \", _jsx(_components.code, {\n children: \"status\"\n }), \" is \", _jsx(_components.code, {\n children: \"ready\"\n }), \" (or \", _jsx(_components.code, {\n children: \"failed\"\n }), \") before\\nreading its rows. Only one background collection runs per account at a\\ntime; a second one gets \", _jsx(_components.code, {\n children: \"409 collection_in_progress\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If nothing matched the filters, the response is \", _jsx(_components.code, {\n children: \"200\"\n }), \" with\\n\", _jsx(_components.code, {\n children: \"data: null\"\n }), \" and a \", _jsx(_components.code, {\n children: \"note\"\n }), \": no dataset is created for an empty result,\\nand the daily collection slot is given back.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"my_posts\"\n }), \" and \", _jsx(_components.code, {\n children: \"my_replies\"\n }), \" read the account’s own synced posts: they\\ntake no \", _jsx(_components.code, {\n children: \"target\"\n }), \", always finish inside the request, and ignore the\\nprofile filters (the response \", _jsx(_components.code, {\n children: \"note\"\n }), \" says so rather than dropping them\\nsilently).\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Cost.\"\n }), \" Every collection counts against a limit of 10 per day for\\nthe account, shared with the collections Ask SuperX runs in the app\\n(\", _jsx(_components.code, {\n children: \"429 collection_quota_exceeded\"\n }), \"). Collections that read X also spend\\nthe enrichment allowance: one unit for the size estimate, plus the\\npages the walk is expected to need, all charged before the walk\\nstarts so \", _jsx(_components.code, {\n children: \"X-RateLimit-Remaining\"\n }), \" stays honest about work that\\noutlives the response. Own-content collections spend nothing.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Research is charged in AI credits, not collections.\"\n }), \"\\n\", _jsx(_components.code, {\n children: \"source: \\\"research\\\"\"\n }), \" costs a flat 1 credit per profile ACTUALLY\\nresearched: profiles that could not be researched come back in\\n\", _jsx(_components.code, {\n children: \"meta.skipped\"\n }), \" and their credits are returned. It spends one of the\\nplan’s daily profile-research runs (\", _jsx(_components.code, {\n children: \"429 ai_action_limited\"\n }), \" with\\n\", _jsx(_components.code, {\n children: \"scope: \\\"account\\\"\"\n }), \") and a slice of a platform-wide fair-use ceiling on\\nlive-data actions shared by every SuperX account\\n(\", _jsx(_components.code, {\n children: \"429 ai_action_limited\"\n }), \" with \", _jsx(_components.code, {\n children: \"scope: \\\"platform\\\"\"\n }), \"), and it does NOT\\ncount against the 10 collections a day. An empty credit pool is\\n\", _jsx(_components.code, {\n children: \"429 ai_credits_exhausted\"\n }), \". What was charged comes back in\\n\", _jsx(_components.code, {\n children: \"meta.credits_charged\"\n }), \" and in the \", _jsx(_components.code, {\n children: \"X-Credits-*\"\n }), \" headers on the \", _jsx(_components.code, {\n children: \"200\"\n }), \";\\na background research run settles when it finishes, so its \", _jsx(_components.code, {\n children: \"202\"\n }), \"\\ncarries neither, and the figure lands on \", _jsx(_components.code, {\n children: \"GET /v1/me\"\n }), \" and your ledger.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Datasets created here appear alongside the ones Ask SuperX built, and\\nare kept for 30 days.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send an \", _jsx(_components.code, {\n children: \"Idempotency-Key\"\n }), \" header to make retries safe: the same key\\nwith the same body replays the first response with\\n\", _jsx(_components.code, {\n children: \"Idempotency-Replayed: true\"\n }), \", and the same key with a different body\\nis rejected with \", _jsx(_components.code, {\n children: \"409 idempotency_key_reuse\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Collect an audience into a dataset","description":"Collect the repliers, quote posters or reposters of a post, the\nmembers of a public X list, or the account's own posts or replies,\ninto a stored dataset you can then read, export, or copy into a\ncontact list.\n\n`source: \"research\"` is the exception: instead of walking an audience\nit reads people's recent posts and writes a short outreach brief for\neach one (what they do, what they are building, recent topics,\npersonalization hooks that QUOTE their real posts, and an opener\nangle). Give it exactly one source - `handles`, `list_id`, `agent_id`\nor `dataset_id` - plus optional `focus`, `title` and `max_rows` (1-25,\ndefault 10). The briefs land as an ordinary dataset, so\n`GET /v1/datasets/{id}/rows`, `/export` and `/contacts` read them\nunchanged. More than 5 profiles research in the background and answer\n`202`. If none of them could be researched, the answer is `200` with\n`data: null`, the reasons in `meta.skipped`, and every credit\nreturned.\n\n**This endpoint can answer before the work is finished.** A small\ncollection runs inside the request and answers `200` with a `ready`\ndataset. A big one, **or one whose size cannot be established up\nfront**, answers `202` with a `collecting` dataset: poll\n`GET /v1/datasets/{id}` until `status` is `ready` (or `failed`) before\nreading its rows. Only one background collection runs per account at a\ntime; a second one gets `409 collection_in_progress`.\n\nIf nothing matched the filters, the response is `200` with\n`data: null` and a `note`: no dataset is created for an empty result,\nand the daily collection slot is given back.\n\n`my_posts` and `my_replies` read the account's own synced posts: they\ntake no `target`, always finish inside the request, and ignore the\nprofile filters (the response `note` says so rather than dropping them\nsilently).\n\n**Cost.** Every collection counts against a limit of 10 per day for\nthe account, shared with the collections Ask SuperX runs in the app\n(`429 collection_quota_exceeded`). Collections that read X also spend\nthe enrichment allowance: one unit for the size estimate, plus the\npages the walk is expected to need, all charged before the walk\nstarts so `X-RateLimit-Remaining` stays honest about work that\noutlives the response. Own-content collections spend nothing.\n\n**Research is charged in AI credits, not collections.**\n`source: \"research\"` costs a flat 1 credit per profile ACTUALLY\nresearched: profiles that could not be researched come back in\n`meta.skipped` and their credits are returned. It spends one of the\nplan's daily profile-research runs (`429 ai_action_limited` with\n`scope: \"account\"`) and a slice of a platform-wide fair-use ceiling on\nlive-data actions shared by every SuperX account\n(`429 ai_action_limited` with `scope: \"platform\"`), and it does NOT\ncount against the 10 collections a day. An empty credit pool is\n`429 ai_credits_exhausted`. What was charged comes back in\n`meta.credits_charged` and in the `X-Credits-*` headers on the `200`;\na background research run settles when it finishes, so its `202`\ncarries neither, and the figure lands on `GET /v1/me` and your ledger.\n\nDatasets created here appear alongside the ones Ask SuperX built, and\nare kept for 30 days.\n\nSend an `Idempotency-Key` header to make retries safe: the same key\nwith the same body replays the first response with\n`Idempotency-Replayed: true`, and the same key with a different body\nis rejected with `409 idempotency_key_reuse`.\n","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/datasets","href":"/api-reference/datasets/collect-an-audience-into-a-dataset","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["Datasets"],"operationId":"createDataset","summary":"Collect an audience into a dataset","description":"Collect the repliers, quote posters or reposters of a post, the\nmembers of a public X list, or the account's own posts or replies,\ninto a stored dataset you can then read, export, or copy into a\ncontact list.\n\n`source: \"research\"` is the exception: instead of walking an audience\nit reads people's recent posts and writes a short outreach brief for\neach one (what they do, what they are building, recent topics,\npersonalization hooks that QUOTE their real posts, and an opener\nangle). Give it exactly one source - `handles`, `list_id`, `agent_id`\nor `dataset_id` - plus optional `focus`, `title` and `max_rows` (1-25,\ndefault 10). The briefs land as an ordinary dataset, so\n`GET /v1/datasets/{id}/rows`, `/export` and `/contacts` read them\nunchanged. More than 5 profiles research in the background and answer\n`202`. If none of them could be researched, the answer is `200` with\n`data: null`, the reasons in `meta.skipped`, and every credit\nreturned.\n\n**This endpoint can answer before the work is finished.** A small\ncollection runs inside the request and answers `200` with a `ready`\ndataset. A big one, **or one whose size cannot be established up\nfront**, answers `202` with a `collecting` dataset: poll\n`GET /v1/datasets/{id}` until `status` is `ready` (or `failed`) before\nreading its rows. Only one background collection runs per account at a\ntime; a second one gets `409 collection_in_progress`.\n\nIf nothing matched the filters, the response is `200` with\n`data: null` and a `note`: no dataset is created for an empty result,\nand the daily collection slot is given back.\n\n`my_posts` and `my_replies` read the account's own synced posts: they\ntake no `target`, always finish inside the request, and ignore the\nprofile filters (the response `note` says so rather than dropping them\nsilently).\n\n**Cost.** Every collection counts against a limit of 10 per day for\nthe account, shared with the collections Ask SuperX runs in the app\n(`429 collection_quota_exceeded`). Collections that read X also spend\nthe enrichment allowance: one unit for the size estimate, plus the\npages the walk is expected to need, all charged before the walk\nstarts so `X-RateLimit-Remaining` stays honest about work that\noutlives the response. Own-content collections spend nothing.\n\n**Research is charged in AI credits, not collections.**\n`source: \"research\"` costs a flat 1 credit per profile ACTUALLY\nresearched: profiles that could not be researched come back in\n`meta.skipped` and their credits are returned. It spends one of the\nplan's daily profile-research runs (`429 ai_action_limited` with\n`scope: \"account\"`) and a slice of a platform-wide fair-use ceiling on\nlive-data actions shared by every SuperX account\n(`429 ai_action_limited` with `scope: \"platform\"`), and it does NOT\ncount against the 10 collections a day. An empty credit pool is\n`429 ai_credits_exhausted`. What was charged comes back in\n`meta.credits_charged` and in the `X-Credits-*` headers on the `200`;\na background research run settles when it finishes, so its `202`\ncarries neither, and the figure lands on `GET /v1/me` and your ledger.\n\nDatasets created here appear alongside the ones Ask SuperX built, and\nare kept for 30 days.\n\nSend an `Idempotency-Key` header to make retries safe: the same key\nwith the same body replays the first response with\n`Idempotency-Replayed: true`, and the same key with a different body\nis rejected with `409 idempotency_key_reuse`.\n","parameters":["7990d9df-e7fd-4b92-aa6d-7684861ac91d"],"requestBody":"80ba1b04-db15-4cea-ab9d-46e2aa18dd56","responses":{"200":"9a883ad8-5443-4b98-b861-9273ee34a1ad","202":"604a0c88-b3b4-4d00-86d6-ea40d4eed01a","400":"9148242b-6efe-425c-ba73-501078eb0883","401":"64b52d42-2192-4451-8dfc-837b014d898b","403":"beb3fc17-7528-4872-a9eb-c8b9d2bfcb57","404":"646bdb80-7133-4765-83e0-80c1316defc5","409":"3ad7398e-6517-4cd8-859e-0ed70e5ca414","429":"a4c8ed55-f0af-4220-82d6-ad036a75b97a","500":"c3c77dd0-d867-4595-aa2c-88d76c8f4f24","502":"2deca323-6ea8-4c33-aa37-62337ac39f32","503":"d9389a40-423d-4c4e-a325-0c4bc54e70b2"},"method":"post","type":"path","servers":["3d538a38-214d-4480-97a3-9a44d5c3102b"],"security":["d3f7d345-7007-489f-b114-dac4df3cb92f"],"path":"/v1/datasets","baseUrlOptions":["https://api.superx.so"],"title":"Collect an audience into a dataset","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"7990d9df-e7fd-4b92-aa6d-7684861ac91d":{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key (max 64 characters) for safe retries. Replays carry the \"Idempotency-Replayed\" response header set to \"true\". Keys are retained for 24 hours.","schema":{"type":"string","maxLength":64,"isRequired":false,"description":"Unique key (max 64 characters) for safe retries. Replays carry the \"Idempotency-Replayed\" response header set to \"true\". Keys are retained for 24 hours.","uniqueKey":"","typeLabel":"string"}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source"],"properties":{"source":{"type":"string","enum":["repliers","quoters","reposters","list_members","my_replies","my_posts","research"],"description":"Who to collect. repliers, quoters and reposters need a post\ntarget; list_members needs a public X list; my_posts and\nmy_replies read the account's own synced posts and take no\ntarget.\n\n`research` is different: it reads people's recent posts and writes\nan outreach brief per person instead of walking an audience. It\ntakes exactly ONE of `handles`, `list_id`, `agent_id` or\n`dataset_id`, plus `focus` and a `max_rows` of 1-25 (default 10),\nand ignores `target` and `filters`.\n","isRequired":true,"uniqueKey":"source","typeLabel":"enum\u003cstring>"},"target":{"type":"string","description":"An x.com post URL or numeric post id, or for list_members an\nx.com list URL (/i/lists/\u003cid>) or numeric list id. Omit for\nmy_posts and my_replies.\n","uniqueKey":"target","typeLabel":"string"},"title":{"type":"string","maxLength":120,"description":"Title for the dataset. A sensible one is generated when omitted.","uniqueKey":"title","typeLabel":"string"},"max_rows":{"type":"integer","minimum":1,"maximum":1000,"default":500,"description":"Rows to collect at most. For `source: \"research\"` the range is\n1-25 and the default is 10 (one profile per row).\n","uniqueKey":"max_rows","typeLabel":"integer"},"account_id":{"type":"string","description":"Which of your accounts to collect as. Omit for the main account.","uniqueKey":"account_id","typeLabel":"string"},"handles":{"type":"array","maxItems":25,"items":{"type":"string","uniqueKey":"handles.items.[INDEX]","typeLabel":"string"},"description":"`research` only: research these X handles (with or without the @). Exactly one source field.","uniqueKey":"handles","typeLabel":"string[]"},"list_id":{"type":"string","description":"`research` only: research the members of this contact list. Exactly one source field.","uniqueKey":"list_id","typeLabel":"string"},"agent_id":{"type":"integer","minimum":1,"description":"`research` only: research this signal agent's leads. Exactly one source field.","uniqueKey":"agent_id","typeLabel":"integer"},"dataset_id":{"type":"string","description":"`research` only: research the people in this dataset. Exactly one source field.","uniqueKey":"dataset_id","typeLabel":"string"},"focus":{"type":"string","maxLength":300,"description":"`research` only: an optional steer, e.g. \"founders who might need audience-growth tooling\".","uniqueKey":"focus","typeLabel":"string"},"filters":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string","uniqueKey":"filters.keywords.items.[INDEX]","typeLabel":"string"},"description":"Keep only rows whose reply, quote or (own content) post text\ncontains one of these. Not applied to reposters or list\nmembers, whose rows carry no text.\n","uniqueKey":"filters.keywords","typeLabel":"string[]"},"bio_keywords":{"type":"array","items":{"type":"string","uniqueKey":"filters.bio_keywords.items.[INDEX]","typeLabel":"string"},"description":"Keep only people whose X bio contains one of these. Ignored for own content.","uniqueKey":"filters.bio_keywords","typeLabel":"string[]"},"min_followers":{"type":"integer","minimum":0,"description":"Keep only people with at least this many followers. Ignored for own content.","uniqueKey":"filters.min_followers","typeLabel":"integer"},"require_website":{"type":"boolean","description":"Keep only people with a website link in their profile. Ignored for own content.","uniqueKey":"filters.require_website","typeLabel":"boolean"},"require_can_dm":{"type":"boolean","description":"Keep only people whose DMs look open. Ignored for own content.","uniqueKey":"filters.require_can_dm","typeLabel":"boolean"},"since_days":{"type":"integer","minimum":1,"description":"Own content only: keep posts from the last N days.","uniqueKey":"filters.since_days","typeLabel":"integer"},"sort":{"type":"string","enum":["recent","likes","impressions"],"description":"Own content only: which posts to keep when max_rows cuts the list.","uniqueKey":"filters.sort","typeLabel":"enum\u003cstring>"}},"uniqueKey":"filters","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"source":"repliers","target":"https://x.com/robj3d3/status/1234567890123456789","title":"Repliers to my launch post","max_rows":500,"filters":{"min_followers":500,"require_can_dm":true}},"examples":{"Example":{"title":"Example","value":{"source":"repliers","target":"https://x.com/robj3d3/status/1234567890123456789","title":"Repliers to my launch post","max_rows":500,"filters":{"min_followers":500,"require_can_dm":true}}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"9a883ad8-5443-4b98-b861-9273ee34a1ad":{"description":"The collection finished inside the request. `data` is null when\nnothing matched, with a `note` explaining why. A research run\nadds `meta` (what was requested, what was researched, what it\ncost) and the `X-Credits-*` headers.\n","headers":{"X-RateLimit-Limit":{"description":"The limit of the rate window closest to exhaustion.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when that window resets.","schema":{"type":"integer"}},"X-Credits-Charged":{"description":"Credits kept for this call. Research runs only.","schema":{"type":"integer"}},"X-Credits-Remaining":{"description":"AI credits left in the account's pool, bonus credits included.","schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Unix timestamp (seconds) when the AI credit pool refills.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"Pass this to the other dataset endpoints.","uniqueKey":"data.oneOf.0.id","typeLabel":"string"},"title":{"type":"string","uniqueKey":"data.oneOf.0.title","typeLabel":"string"},"source":{"type":"string","enum":["repliers","quoters","reposters","list_members","my_replies","my_posts","research"],"description":"What the collection walked. `my_posts` / `my_replies` hold posts, everything else holds people.","uniqueKey":"data.oneOf.0.source","typeLabel":"enum\u003cstring>"},"status":{"type":"string","enum":["ready","collecting","failed"],"uniqueKey":"data.oneOf.0.status","typeLabel":"enum\u003cstring>"},"target_ref":{"type":"string","description":"What the collection was pointed at - a post id, an X list id, or free text for a research brief.","uniqueKey":"data.oneOf.0.target_ref","typeLabel":"string"},"x_account_id":{"type":"string","description":"The X account the collection ran as. Not a filter - datasets belong to the key owner, not to one account.","uniqueKey":"data.oneOf.0.x_account_id","typeLabel":"string"},"ask_chat_id":{"oneOf":[{"type":"string","description":"The Ask SuperX chat the dataset was built in, when known.","uniqueKey":"data.oneOf.0.ask_chat_id.oneOf.0","typeLabel":"string"},{"type":"null","description":"The Ask SuperX chat the dataset was built in, when known.","uniqueKey":"data.oneOf.0.ask_chat_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.oneOf.0.ask_chat_id","typeLabel":"string | null"},"columns":{"type":"array","items":{"type":"string","uniqueKey":"data.oneOf.0.columns.items.[INDEX]","typeLabel":"string"},"description":"The row keys this dataset carries, in export order.","uniqueKey":"data.oneOf.0.columns","typeLabel":"string[]"},"row_count":{"type":"integer","uniqueKey":"data.oneOf.0.row_count","typeLabel":"integer"},"scanned_count":{"type":"integer","description":"What the walk went through (people datasets), or the rows kept (own-content datasets).","uniqueKey":"data.oneOf.0.scanned_count","typeLabel":"integer"},"total_estimate":{"oneOf":[{"type":"integer","uniqueKey":"data.oneOf.0.total_estimate.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"data.oneOf.0.total_estimate.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.oneOf.0.total_estimate","typeLabel":"integer | null"},"coverage_complete":{"type":"boolean","description":"False when the collection hit its row cap before the end.","uniqueKey":"data.oneOf.0.coverage_complete","typeLabel":"boolean"},"has_people":{"type":"boolean","description":"False for own-content datasets - there is nobody in them to add to a contact list.","uniqueKey":"data.oneOf.0.has_people","typeLabel":"boolean"},"created_at":{"type":"string","format":"date-time","uniqueKey":"data.oneOf.0.created_at","typeLabel":"string\u003cdate-time>"},"expires_at":{"type":"string","format":"date-time","description":"Datasets are kept for 30 days.","uniqueKey":"data.oneOf.0.expires_at","typeLabel":"string\u003cdate-time>"},"coverage":{"type":"string","description":"An honest one-line coverage statement. Ready datasets only.","uniqueKey":"data.oneOf.0.coverage","typeLabel":"string"},"filters":{"type":"object","additionalProperties":true,"description":"The filters the collection applied. Ready datasets only.","uniqueKey":"data.oneOf.0.filters","typeLabel":"object"},"progress":{"type":"object","description":"Live progress of a collection that is still running.","properties":{"page":{"type":"integer","uniqueKey":"data.oneOf.0.progress.page","typeLabel":"integer"},"scanned":{"type":"integer","uniqueKey":"data.oneOf.0.progress.scanned","typeLabel":"integer"},"matched":{"type":"integer","uniqueKey":"data.oneOf.0.progress.matched","typeLabel":"integer"},"total_estimate":{"oneOf":[{"type":"integer","uniqueKey":"data.oneOf.0.progress.total_estimate.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"data.oneOf.0.progress.total_estimate.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.oneOf.0.progress.total_estimate","typeLabel":"integer | null"},"started_at":{"type":"string","format":"date-time","uniqueKey":"data.oneOf.0.progress.started_at","typeLabel":"string\u003cdate-time>"}},"uniqueKey":"data.oneOf.0.progress","typeLabel":"object"},"failure_note":{"type":"string","description":"Why the collection stopped. Failed datasets only.","uniqueKey":"data.oneOf.0.failure_note","typeLabel":"string"}},"uniqueKey":"data.oneOf.0","typeLabel":"object"},{"type":"null","uniqueKey":"data.oneOf.1","typeLabel":"null"}],"uniqueKey":"data","typeLabel":"object | null"},"meta":{"type":"object","description":"Research runs only. Absent on audience collections.","properties":{"requested":{"type":"integer","description":"Profiles the source resolved to.","uniqueKey":"meta.requested","typeLabel":"integer"},"researched":{"type":"integer","description":"Profiles a brief was actually written for.","uniqueKey":"meta.researched","typeLabel":"integer"},"credits_charged":{"type":"integer","description":"Credits kept, one per researched profile.","uniqueKey":"meta.credits_charged","typeLabel":"integer"},"skipped":{"type":"array","description":"Profiles that produced no brief, with the reason.","items":{"type":"object","properties":{"handle":{"oneOf":[{"type":"string","uniqueKey":"meta.skipped.items.[INDEX].handle.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"meta.skipped.items.[INDEX].handle.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.skipped.items.[INDEX].handle","typeLabel":"string | null"},"reason":{"type":"string","uniqueKey":"meta.skipped.items.[INDEX].reason","typeLabel":"string"}},"uniqueKey":"meta.skipped.items.[INDEX]","typeLabel":"object"},"uniqueKey":"meta.skipped","typeLabel":"object[]"}},"uniqueKey":"meta","typeLabel":"object"},"note":{"type":"string","description":"Present when something needs saying, such as an empty result or ignored filters.","uniqueKey":"note","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"collection":{"title":"collection","value":{"data":{"id":"VKcPAVU1FSkx4kzPuehGK","title":"Repliers to my launch post","source":"repliers","status":"ready","target_ref":"1234567890123456789","x_account_id":"1178367350552305665","ask_chat_id":null,"columns":["handle","name","bio","website","followers","following","location","can_dm","verified"],"row_count":64,"scanned_count":71,"total_estimate":71,"coverage_complete":true,"has_people":true,"created_at":"2026-09-10T10:12:00.000Z","expires_at":"2026-10-10T10:12:00.000Z","coverage":"Includes all 71 direct replies to the post.","filters":{"minFollowers":500,"requireCanDm":true}}}},"research":{"title":"research","value":{"data":{"id":"Rk2PAVU1FSkx4kzPuehGK","title":"Outreach briefs (3 profiles)","source":"research","status":"ready","target_ref":"handles","x_account_id":"1178367350552305665","ask_chat_id":null,"columns":["handle","name","followers","can_dm","bio","does","building","recent_topics","hooks","opener_angle"],"row_count":3,"scanned_count":3,"total_estimate":3,"coverage_complete":true,"has_people":true,"created_at":"2026-09-10T10:12:00.000Z","expires_at":"2026-10-10T10:12:00.000Z","coverage":"Researched all 3 requested profiles."},"meta":{"requested":3,"researched":3,"credits_charged":3},"note":"Every hook quotes one of the person's real posts; proposed quotes that failed the verbatim check were dropped. Briefs are text for a person to act on: read the full rows with GET /v1/datasets/{id}/rows."}}},"exampleType":"examples"}},"exampleType":"examples"},"604a0c88-b3b4-4d00-86d6-ea40d4eed01a":{"description":"The collection, or the research run, started in the background.\nPoll `GET /v1/datasets/{id}` until `status` is `ready`. Research\nsettles its credits when the run finishes, so no `X-Credits-*`\nheader is sent here and `meta` carries no charge.\n","headers":{"X-RateLimit-Limit":{"description":"The limit of the rate window closest to exhaustion.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when that window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Pass this to the other dataset endpoints.","uniqueKey":"data.id","typeLabel":"string"},"title":{"type":"string","uniqueKey":"data.title","typeLabel":"string"},"source":{"type":"string","enum":["repliers","quoters","reposters","list_members","my_replies","my_posts","research"],"description":"What the collection walked. `my_posts` / `my_replies` hold posts, everything else holds people.","uniqueKey":"data.source","typeLabel":"enum\u003cstring>"},"status":{"type":"string","enum":["ready","collecting","failed"],"uniqueKey":"data.status","typeLabel":"enum\u003cstring>"},"target_ref":{"type":"string","description":"What the collection was pointed at - a post id, an X list id, or free text for a research brief.","uniqueKey":"data.target_ref","typeLabel":"string"},"x_account_id":{"type":"string","description":"The X account the collection ran as. Not a filter - datasets belong to the key owner, not to one account.","uniqueKey":"data.x_account_id","typeLabel":"string"},"ask_chat_id":{"oneOf":[{"type":"string","description":"The Ask SuperX chat the dataset was built in, when known.","uniqueKey":"data.ask_chat_id.oneOf.0","typeLabel":"string"},{"type":"null","description":"The Ask SuperX chat the dataset was built in, when known.","uniqueKey":"data.ask_chat_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.ask_chat_id","typeLabel":"string | null"},"columns":{"type":"array","items":{"type":"string","uniqueKey":"data.columns.items.[INDEX]","typeLabel":"string"},"description":"The row keys this dataset carries, in export order.","uniqueKey":"data.columns","typeLabel":"string[]"},"row_count":{"type":"integer","uniqueKey":"data.row_count","typeLabel":"integer"},"scanned_count":{"type":"integer","description":"What the walk went through (people datasets), or the rows kept (own-content datasets).","uniqueKey":"data.scanned_count","typeLabel":"integer"},"total_estimate":{"oneOf":[{"type":"integer","uniqueKey":"data.total_estimate.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"data.total_estimate.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.total_estimate","typeLabel":"integer | null"},"coverage_complete":{"type":"boolean","description":"False when the collection hit its row cap before the end.","uniqueKey":"data.coverage_complete","typeLabel":"boolean"},"has_people":{"type":"boolean","description":"False for own-content datasets - there is nobody in them to add to a contact list.","uniqueKey":"data.has_people","typeLabel":"boolean"},"created_at":{"type":"string","format":"date-time","uniqueKey":"data.created_at","typeLabel":"string\u003cdate-time>"},"expires_at":{"type":"string","format":"date-time","description":"Datasets are kept for 30 days.","uniqueKey":"data.expires_at","typeLabel":"string\u003cdate-time>"},"coverage":{"type":"string","description":"An honest one-line coverage statement. Ready datasets only.","uniqueKey":"data.coverage","typeLabel":"string"},"filters":{"type":"object","additionalProperties":true,"description":"The filters the collection applied. Ready datasets only.","uniqueKey":"data.filters","typeLabel":"object"},"progress":{"type":"object","description":"Live progress of a collection that is still running.","properties":{"page":{"type":"integer","uniqueKey":"data.progress.page","typeLabel":"integer"},"scanned":{"type":"integer","uniqueKey":"data.progress.scanned","typeLabel":"integer"},"matched":{"type":"integer","uniqueKey":"data.progress.matched","typeLabel":"integer"},"total_estimate":{"oneOf":[{"type":"integer","uniqueKey":"data.progress.total_estimate.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"data.progress.total_estimate.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.progress.total_estimate","typeLabel":"integer | null"},"started_at":{"type":"string","format":"date-time","uniqueKey":"data.progress.started_at","typeLabel":"string\u003cdate-time>"}},"uniqueKey":"data.progress","typeLabel":"object"},"failure_note":{"type":"string","description":"Why the collection stopped. Failed datasets only.","uniqueKey":"data.failure_note","typeLabel":"string"}},"uniqueKey":"data","typeLabel":"object"},"meta":{"type":"object","description":"Research runs only. Absent on audience collections.","properties":{"requested":{"type":"integer","description":"Profiles the source resolved to.","uniqueKey":"meta.requested","typeLabel":"integer"},"skipped":{"type":"array","description":"Profiles rejected before the run started, with the reason.","items":{"type":"object","properties":{"handle":{"oneOf":[{"type":"string","uniqueKey":"meta.skipped.items.[INDEX].handle.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"meta.skipped.items.[INDEX].handle.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.skipped.items.[INDEX].handle","typeLabel":"string | null"},"reason":{"type":"string","uniqueKey":"meta.skipped.items.[INDEX].reason","typeLabel":"string"}},"uniqueKey":"meta.skipped.items.[INDEX]","typeLabel":"object"},"uniqueKey":"meta.skipped","typeLabel":"object[]"}},"uniqueKey":"meta","typeLabel":"object"},"note":{"type":"string","uniqueKey":"note","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"example":{"data":{"id":"Jc9PxVU1FSkx4kzPuehGK","title":"Repliers to my launch post","source":"repliers","status":"collecting","target_ref":"1234567890123456789","x_account_id":"1178367350552305665","ask_chat_id":null,"columns":["handle","name","bio","website","followers","following","location","can_dm","verified"],"row_count":0,"scanned_count":0,"total_estimate":4200,"coverage_complete":false,"has_people":true,"created_at":"2026-09-10T10:12:00.000Z","expires_at":"2026-10-10T10:12:00.000Z","progress":{"page":0,"scanned":0,"matched":0,"total_estimate":4200,"started_at":"2026-09-10T10:12:00.000Z"}},"note":"Collecting in the background; poll GET /v1/datasets/{id} until status is ready."},"examples":{"Example":{"title":"Example","value":{"data":{"id":"Jc9PxVU1FSkx4kzPuehGK","title":"Repliers to my launch post","source":"repliers","status":"collecting","target_ref":"1234567890123456789","x_account_id":"1178367350552305665","ask_chat_id":null,"columns":["handle","name","bio","website","followers","following","location","can_dm","verified"],"row_count":0,"scanned_count":0,"total_estimate":4200,"coverage_complete":false,"has_people":true,"created_at":"2026-09-10T10:12:00.000Z","expires_at":"2026-10-10T10:12:00.000Z","progress":{"page":0,"scanned":0,"matched":0,"total_estimate":4200,"started_at":"2026-09-10T10:12:00.000Z"}},"note":"Collecting in the background; poll GET /v1/datasets/{id} until status is ready."}}},"exampleType":"examples"}},"exampleType":"examples"},"9148242b-6efe-425c-ba73-501078eb0883":{"description":"A parameter is missing, malformed, or out of range.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying (rate-limit errors only).","uniqueKey":"error.retry_after","typeLabel":"integer"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"invalid_parameter","message":"since must be a UTC ISO-8601 timestamp"}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"invalid_parameter","message":"since must be a UTC ISO-8601 timestamp"}}}},"exampleType":"examples"}},"exampleType":"examples"},"64b52d42-2192-4451-8dfc-837b014d898b":{"description":"Missing/malformed Authorization header (`unauthorized`) or an unknown/revoked key (`invalid_api_key`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying (rate-limit errors only).","uniqueKey":"error.retry_after","typeLabel":"integer"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"invalid_api_key","message":"Unknown or revoked API key"}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"invalid_api_key","message":"Unknown or revoked API key"}}}},"exampleType":"examples"}},"exampleType":"examples"},"beb3fc17-7528-4872-a9eb-c8b9d2bfcb57":{"description":"Read-only key (`insufficient_scope`), an account shared with you (`writes_main_account_only`; shared accounts are read-only through the API, your own linked accounts are not), or a lapsed subscription (legacy string envelope).","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","isRequired":true,"uniqueKey":"oneOf.0.error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.error.message","typeLabel":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying (rate-limit errors only).","uniqueKey":"oneOf.0.error.retry_after","typeLabel":"integer"}},"isRequired":true,"uniqueKey":"oneOf.0.error","typeLabel":"object"}},"uniqueKey":"oneOf.0","typeLabel":"object"},{"type":"object","description":"Legacy shape used ONLY by the shared subscription middleware: a plain\nstring `error` field. Seen on `403` when the subscription has lapsed\n(string starts with \"subscription_required:\") and on `500` when\nsubscription verification fails (string starts with \"internal_error:\").\n","required":["error"],"properties":{"error":{"type":"string","example":"subscription_required: The SuperX API requires an active subscription","isRequired":true,"uniqueKey":"oneOf.1.error","typeLabel":"string"}},"uniqueKey":"oneOf.1","typeLabel":"object"}],"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"insufficient_scope","message":"This API key is read-only. Create a key with the write scope to use this endpoint."}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"insufficient_scope","message":"This API key is read-only. Create a key with the write scope to use this endpoint."}}}},"exampleType":"examples"}},"exampleType":"examples"},"646bdb80-7133-4765-83e0-80c1316defc5":{"description":"`account_not_found` when `account_id` is not one of your accounts.\nOn `source: \"research\"` the source id is named too:\n`list_not_found`, `agent_not_found`, or `not_found` for a dataset\nid that is unknown or expired.\n","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying (rate-limit errors only).","uniqueKey":"error.retry_after","typeLabel":"integer"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"account_not_found":{"title":"account_not_found","value":{"error":{"code":"account_not_found","message":"No account with that id belongs to this key"}}},"list_not_found":{"title":"list_not_found","value":{"error":{"code":"list_not_found","message":"No contact list with that id belongs to this account."}}},"agent_not_found":{"title":"agent_not_found","value":{"error":{"code":"agent_not_found","message":"No signal agent with that id belongs to this account."}}},"not_found":{"title":"not_found","value":{"error":{"code":"not_found","message":"No dataset with that id. Use the dataset_id from a collect_audience or refine_dataset result."}}}},"exampleType":"examples"}},"exampleType":"examples"},"3ad7398e-6517-4cd8-859e-0ed70e5ca414":{"description":"Another background collection is still running for this account\n(`collection_in_progress`), the `Idempotency-Key` was reused with a\ndifferent request body (`idempotency_key_reuse`), or the dataset a\nresearch run was pointed at is not ready yet\n(`dataset_not_ready`, carrying `dataset_status`). None of them\nstarted anything.\n","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying (rate-limit errors only).","uniqueKey":"error.retry_after","typeLabel":"integer"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"dataset_not_ready":{"title":"dataset_not_ready","value":{"error":{"code":"dataset_not_ready","message":"The source dataset is not ready yet. Poll GET /v1/datasets/{id} until status is ready, then research it.","dataset_status":"collecting"}}},"collection_in_progress":{"title":"collection_in_progress","value":{"error":{"code":"collection_in_progress","message":"Another audience collection is still running for this account. Poll it with GET /v1/datasets/{id} and start this one when it finishes."}}},"idempotency_key_reuse":{"title":"idempotency_key_reuse","value":{"error":{"code":"idempotency_key_reuse","message":"This Idempotency-Key was already used with a different request body."}}}},"exampleType":"examples"}},"exampleType":"examples"},"a4c8ed55-f0af-4220-82d6-ad036a75b97a":{"description":"Read `error.code`. A collection is refused when today's 10\ncollections are used up (`collection_quota_exceeded`, shared with\nAsk SuperX in the app) or the enrichment allowance the walk needs\nis exhausted (`rate_limited`). A research run is refused when the\nplan's daily research runs are used up (`ai_action_limited` with\n`scope: \"account\"`), when the platform-wide fair-use ceiling on\nlive-data actions is reached (`ai_action_limited` with\n`scope: \"platform\"`, shared by every account and not about your\nown quota), or when the AI credit pool is empty\n(`ai_credits_exhausted`). Every flavour carries `Retry-After`, and\nthe two `ai_action_limited` ones carry `reset_at` (unix seconds)\nas well. Nothing was started or charged.\n","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-Credits-Remaining":{"description":"Credits left in the pool. Sent only on `ai_credits_exhausted`.","schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Unix seconds when the pool refills. Sent only on `ai_credits_exhausted`.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","isRequired":true,"uniqueKey":"oneOf.0.error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.error.message","typeLabel":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying (rate-limit errors only).","uniqueKey":"oneOf.0.error.retry_after","typeLabel":"integer"}},"isRequired":true,"uniqueKey":"oneOf.0.error","typeLabel":"object"}},"uniqueKey":"oneOf.0","typeLabel":"object"},{"type":"object","description":"The `429 ai_action_limited` body: a per-day cap on how many times an\nexpensive action can run, counted separately from the credit pool and\nfrom the request rate limits. Sent with a `Retry-After` header. Caps\nreset at midnight UTC.\n\nRead `scope` before telling a user anything: `account` means the\nplan's own daily cap for that action, `platform` means the\nplatform-wide fair-use ceiling on live-data actions, which is shared\nwith every SuperX account. A `platform` refusal is not about this\naccount's quota, so wait and retry rather than reporting the account\nas out.\n","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["ai_action_limited"],"isRequired":true,"uniqueKey":"oneOf.1.error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"oneOf.1.error.message","typeLabel":"string"},"scope":{"type":"string","enum":["account","platform"],"description":"Whose ceiling refused the call: this account's own per-day cap\nfor the action, or the platform-wide fair-use ceiling on\nlive-data actions.\n","uniqueKey":"oneOf.1.error.scope","typeLabel":"enum\u003cstring>"},"retry_after":{"type":"integer","description":"Seconds to wait before the cap resets.","uniqueKey":"oneOf.1.error.retry_after","typeLabel":"integer"},"reset_at":{"type":"integer","description":"Unix seconds when the cap resets (the next UTC midnight).","uniqueKey":"oneOf.1.error.reset_at","typeLabel":"integer"}},"isRequired":true,"uniqueKey":"oneOf.1.error","typeLabel":"object"}},"uniqueKey":"oneOf.1","typeLabel":"object"},{"type":"object","description":"The `429 ai_credits_exhausted` body: the standard envelope plus the\ncredit counters. Sent with a `Retry-After` header and the\n`X-Credits-Remaining` / `X-Credits-Reset` headers. `code` is stable;\nthe counters are additive fields, safe to ignore.\n","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["ai_credits_exhausted"],"isRequired":true,"uniqueKey":"oneOf.2.error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"oneOf.2.error.message","typeLabel":"string"},"credits_required":{"type":"integer","description":"Credits the call needed.","uniqueKey":"oneOf.2.error.credits_required","typeLabel":"integer"},"credits_remaining":{"oneOf":[{"type":"integer","description":"Credits available when it was refused.","uniqueKey":"oneOf.2.error.credits_remaining.oneOf.0","typeLabel":"integer"},{"type":"null","description":"Credits available when it was refused.","uniqueKey":"oneOf.2.error.credits_remaining.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.2.error.credits_remaining","typeLabel":"integer | null"},"reset_at":{"oneOf":[{"type":"integer","description":"Unix timestamp (seconds) when the pool refills.","uniqueKey":"oneOf.2.error.reset_at.oneOf.0","typeLabel":"integer"},{"type":"null","description":"Unix timestamp (seconds) when the pool refills.","uniqueKey":"oneOf.2.error.reset_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.2.error.reset_at","typeLabel":"integer | null"}},"isRequired":true,"uniqueKey":"oneOf.2.error","typeLabel":"object"}},"uniqueKey":"oneOf.2","typeLabel":"object"}],"uniqueKey":"","typeLabel":"object"},"examples":{"collection_quota_exceeded":{"title":"collection_quota_exceeded","value":{"error":{"code":"collection_quota_exceeded","message":"You have used today's audience collections. Existing datasets still read and export; the limit resets at midnight UTC.","retry_after":20400,"limit":10,"reset_at":1789430400}}},"rate_limited":{"title":"rate_limited","value":{"error":{"code":"rate_limited","message":"Rate limit exceeded for the Pro plan (5 enrichment requests/min). This collection needs 4 lookups.","retry_after":42}}},"ai_action_limited_account":{"title":"ai_action_limited_account","value":{"error":{"code":"ai_action_limited","message":"Daily limit reached for this action on your plan (10 profile research runs per day). It resets at midnight UTC.","scope":"account","retry_after":20400,"reset_at":1789430400}}},"ai_action_limited_platform":{"title":"ai_action_limited_platform","value":{"error":{"code":"ai_action_limited","message":"The platform-wide fair-use ceiling for live-data actions has been reached for today. It resets at midnight UTC.","scope":"platform","retry_after":20400,"reset_at":1789430400}}},"ai_credits_exhausted":{"title":"ai_credits_exhausted","value":{"error":{"code":"ai_credits_exhausted","message":"Not enough AI credits. Resets in 5 hours.","credits_required":10,"credits_remaining":4,"reset_at":1790812800}}}},"exampleType":"examples"}},"exampleType":"examples"},"c3c77dd0-d867-4595-aa2c-88d76c8f4f24":{"description":"Unexpected server error. May also use the legacy string envelope when subscription verification fails.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","isRequired":true,"uniqueKey":"oneOf.0.error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.error.message","typeLabel":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying (rate-limit errors only).","uniqueKey":"oneOf.0.error.retry_after","typeLabel":"integer"}},"isRequired":true,"uniqueKey":"oneOf.0.error","typeLabel":"object"}},"uniqueKey":"oneOf.0","typeLabel":"object"},{"type":"object","description":"Legacy shape used ONLY by the shared subscription middleware: a plain\nstring `error` field. Seen on `403` when the subscription has lapsed\n(string starts with \"subscription_required:\") and on `500` when\nsubscription verification fails (string starts with \"internal_error:\").\n","required":["error"],"properties":{"error":{"type":"string","example":"subscription_required: The SuperX API requires an active subscription","isRequired":true,"uniqueKey":"oneOf.1.error","typeLabel":"string"}},"uniqueKey":"oneOf.1","typeLabel":"object"}],"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"internal_error","message":"Failed to fetch posts"}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"internal_error","message":"Failed to fetch posts"}}}},"exampleType":"examples"}},"exampleType":"examples"},"2deca323-6ea8-4c33-aa37-62337ac39f32":{"description":"A dependent SuperX service returned an unexpected response.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying (rate-limit errors only).","uniqueKey":"error.retry_after","typeLabel":"integer"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"upstream_error","message":"Failed to fetch scheduled posts. Try again shortly."}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"upstream_error","message":"Failed to fetch scheduled posts. Try again shortly."}}}},"exampleType":"examples"}},"exampleType":"examples"},"d9389a40-423d-4c4e-a325-0c4bc54e70b2":{"description":"Linked-account verification is temporarily unavailable (fail closed). The main account keeps working.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying (rate-limit errors only).","uniqueKey":"error.retry_after","typeLabel":"integer"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"accounts_unavailable","message":"Account information is temporarily unavailable. Try again shortly."}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"accounts_unavailable","message":"Account information is temporarily unavailable. Try again shortly."}}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"d3f7d345-7007-489f-b114-dac4df3cb92f":{"apiKey":{"type":"http","scheme":"bearer","description":"A SuperX API key (\"sxk_...\"), created in the SuperX app under Account > API / MCP / CLI. Keys are server-side secrets.","scopes":[],"schemeName":"apiKey"}}},"servers":{"3d538a38-214d-4480-97a3-9a44d5c3102b":{"url":"https://api.superx.so"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"A SuperX API key (\"sxk_...\"), created in the SuperX app under Account > API / MCP / CLI. Keys are server-side secrets.","scopes":[],"schemeName":"apiKey"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"A SuperX API key (\"sxk_...\"), created in the SuperX app under Account > API / MCP / CLI. Keys are server-side secrets.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"apiKey","name":"Authorization"}],"title":"apiKey"}]},"originalFileLocation":"api-reference/openapi.yaml"},"subdomain":"superx","siteName":"SuperX","title":"Collect an audience into a dataset - SuperX","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-07T18:31:25.686Z","originalFileLocation":"api-reference/datasets/collect-an-audience-into-a-dataset.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Collect the repliers, quote posters or reposters of a post, the members of a public X list, or the account\u0026#x27;s own posts or replies, into a stored dataset you can then read, export, or copy into a contact list. source: \u0026quot;research\u0026quot; is the exception: instead of walking an audience it reads people\u0026#x27;s recent posts and writes a short outreach brief for each one (what they do, what they are building, recent topics, personalization hooks that QUOTE their real posts, and an opener angle). Give it exactly one source - handles, list_id, agent_id or dataset_id - plus optional focus, title and max_rows (1-25, default 10). The briefs land as an ordinary dataset, so GET /v1/datasets/{id}/rows, /export and /contacts read them unchanged. More than 5 profiles research in the background and answer 202. If none of them could be researched, the answer is 200 with data: null, the reasons in meta.skipped, and every credit returned. This endpoint can answer before the work is finished. A small collection runs inside the request and answers 200 with a ready dataset. A big one, or one whose size cannot be established up front, answers 202 with a collecting dataset: poll GET /v1/datasets/{id} until status is ready (or failed) before reading its rows. Only one background collection runs per account at a time; a second one gets 409 collection_in_progress. If nothing matched the filters, the response is 200 with data: null and a note: no dataset is created for an empty result, and the daily collection slot is given back. my_posts and my_replies read the account\u0026#x27;s own synced posts: they take no target, always finish inside the request, and ignore the profile filters (the response note says so rather than dropping them silently). Cost. Every collection counts against a limit of 10 per day for the account, shared with the collections Ask SuperX runs in the app (429 collection_quota_exceeded). Collections that read X also spend the enrichment allowance: one unit for the size estimate, plus the pages the walk is expected to need, all charged before the walk starts so X-RateLimit-Remaining stays honest about work that outlives the response. Own-content collections spend nothing. Research is charged in AI credits, not collections. source: \u0026quot;research\u0026quot; costs a flat 1 credit per profile ACTUALLY researched: profiles that could not be researched come back in meta.skipped and their credits are returned. It spends one of the plan\u0026#x27;s daily profile-research runs (429 ai_action_limited with scope: \u0026quot;account\u0026quot;) and a slice of a platform-wide fair-use ceiling on live-data actions shared by every SuperX account (429 ai_action_limited with scope: \u0026quot;platform\u0026quot;), and it does NOT count against the 10 collections a day. An empty credit pool is 429 ai_credits_exhausted. What was charged comes back in meta.credits_charged and in the X-Credits-* headers on the 200; a background research run settles when it finishes, so its 202 carries neither, and the figure lands on GET /v1/me and your ledger. Datasets created here appear alongside the ones Ask SuperX built, and are kept for 30 days. Send an Idempotency-Key header to make retries safe: the same key with the same body replays the first response with Idempotency-Replayed: true, and the same key with a different body is rejected with 409 idempotency_key_reuse.\">\u003cmeta data-mint-head name=\"application-name\" content=\"SuperX\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/superx/Ohz_C_TMxE84ikvK/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/superx/Ohz_C_TMxE84ikvK/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/superx/Ohz_C_TMxE84ikvK/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/superx/Ohz_C_TMxE84ikvK/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/superx/Ohz_C_TMxE84ikvK/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/superx/Ohz_C_TMxE84ikvK/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/superx/Ohz_C_TMxE84ikvK/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/superx/Ohz_C_TMxE84ikvK/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/superx/Ohz_C_TMxE84ikvK/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Collect an audience into a dataset - SuperX\">\u003cmeta data-mint-head property=\"og:description\" content=\"Collect the repliers, quote posters or reposters of a post, the members of a public X list, or the account\u0026#x27;s own posts or replies, into a stored dataset you can then read, export, or copy into a contact list. source: \u0026quot;research\u0026quot; is the exception: instead of walking an audience it reads people\u0026#x27;s recent posts and writes a short outreach brief for each one (what they do, what they are building, recent topics, personalization hooks that QUOTE their real posts, and an opener angle). Give it exactly one source - handles, list_id, agent_id or dataset_id - plus optional focus, title and max_rows (1-25, default 10). The briefs land as an ordinary dataset, so GET /v1/datasets/{id}/rows, /export and /contacts read them unchanged. More than 5 profiles research in the background and answer 202. If none of them could be researched, the answer is 200 with data: null, the reasons in meta.skipped, and every credit returned. This endpoint can answer before the work is finished. A small collection runs inside the request and answers 200 with a ready dataset. A big one, or one whose size cannot be established up front, answers 202 with a collecting dataset: poll GET /v1/datasets/{id} until status is ready (or failed) before reading its rows. Only one background collection runs per account at a time; a second one gets 409 collection_in_progress. If nothing matched the filters, the response is 200 with data: null and a note: no dataset is created for an empty result, and the daily collection slot is given back. my_posts and my_replies read the account\u0026#x27;s own synced posts: they take no target, always finish inside the request, and ignore the profile filters (the response note says so rather than dropping them silently). Cost. Every collection counts against a limit of 10 per day for the account, shared with the collections Ask SuperX runs in the app (429 collection_quota_exceeded). Collections that read X also spend the enrichment allowance: one unit for the size estimate, plus the pages the walk is expected to need, all charged before the walk starts so X-RateLimit-Remaining stays honest about work that outlives the response. Own-content collections spend nothing. Research is charged in AI credits, not collections. source: \u0026quot;research\u0026quot; costs a flat 1 credit per profile ACTUALLY researched: profiles that could not be researched come back in meta.skipped and their credits are returned. It spends one of the plan\u0026#x27;s daily profile-research runs (429 ai_action_limited with scope: \u0026quot;account\u0026quot;) and a slice of a platform-wide fair-use ceiling on live-data actions shared by every SuperX account (429 ai_action_limited with scope: \u0026quot;platform\u0026quot;), and it does NOT count against the 10 collections a day. An empty credit pool is 429 ai_credits_exhausted. What was charged comes back in meta.credits_charged and in the X-Credits-* headers on the 200; a background research run settles when it finishes, so its 202 carries neither, and the figure lands on GET /v1/me and your ledger. Datasets created here appear alongside the ones Ask SuperX built, and are kept for 30 days. Send an Idempotency-Key header to make retries safe: the same key with the same body replays the first response with Idempotency-Replayed: true, and the same key with a different body is rejected with 409 idempotency_key_reuse.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"SuperX\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.superx.so/api-reference/datasets/collect-an-audience-into-a-dataset\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://superx.mintlify.app/_mintlify/api/og/v2?division=Datasets\u0026amp;title=Collect+an+audience+into+a+dataset\u0026amp;description=Collect+the+repliers%2C+quote+posters+or+reposters+of+a+post%2C+the%0Amembers+of+a+public+X+list%2C+or+the+account%27s+own+posts+or+replies%2C%0Ainto+a+stored+dataset+you+can\u0026amp;theme=4e9a0bdaa172d4dfc537fe9f\u0026amp;signature=67da5df0e193d87818396f384c400ab5a10fcfa90012a039cc49b19d2a1baebd\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Collect an audience into a dataset - SuperX\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Collect the repliers, quote posters or reposters of a post, the members of a public X list, or the account\u0026#x27;s own posts or replies, into a stored dataset you can then read, export, or copy into a contact list. source: \u0026quot;research\u0026quot; is the exception: instead of walking an audience it reads people\u0026#x27;s recent posts and writes a short outreach brief for each one (what they do, what they are building, recent topics, personalization hooks that QUOTE their real posts, and an opener angle). Give it exactly one source - handles, list_id, agent_id or dataset_id - plus optional focus, title and max_rows (1-25, default 10). The briefs land as an ordinary dataset, so GET /v1/datasets/{id}/rows, /export and /contacts read them unchanged. More than 5 profiles research in the background and answer 202. If none of them could be researched, the answer is 200 with data: null, the reasons in meta.skipped, and every credit returned. This endpoint can answer before the work is finished. A small collection runs inside the request and answers 200 with a ready dataset. A big one, or one whose size cannot be established up front, answers 202 with a collecting dataset: poll GET /v1/datasets/{id} until status is ready (or failed) before reading its rows. Only one background collection runs per account at a time; a second one gets 409 collection_in_progress. If nothing matched the filters, the response is 200 with data: null and a note: no dataset is created for an empty result, and the daily collection slot is given back. my_posts and my_replies read the account\u0026#x27;s own synced posts: they take no target, always finish inside the request, and ignore the profile filters (the response note says so rather than dropping them silently). Cost. Every collection counts against a limit of 10 per day for the account, shared with the collections Ask SuperX runs in the app (429 collection_quota_exceeded). Collections that read X also spend the enrichment allowance: one unit for the size estimate, plus the pages the walk is expected to need, all charged before the walk starts so X-RateLimit-Remaining stays honest about work that outlives the response. Own-content collections spend nothing. Research is charged in AI credits, not collections. source: \u0026quot;research\u0026quot; costs a flat 1 credit per profile ACTUALLY researched: profiles that could not be researched come back in meta.skipped and their credits are returned. It spends one of the plan\u0026#x27;s daily profile-research runs (429 ai_action_limited with scope: \u0026quot;account\u0026quot;) and a slice of a platform-wide fair-use ceiling on live-data actions shared by every SuperX account (429 ai_action_limited with scope: \u0026quot;platform\u0026quot;), and it does NOT count against the 10 collections a day. An empty credit pool is 429 ai_credits_exhausted. What was charged comes back in meta.credits_charged and in the X-Credits-* headers on the 200; a background research run settles when it finishes, so its 202 carries neither, and the figure lands on GET /v1/me and your ledger. Datasets created here appear alongside the ones Ask SuperX built, and are kept for 30 days. Send an Idempotency-Key header to make retries safe: the same key with the same body replays the first response with Idempotency-Replayed: true, and the same key with a different body is rejected with 409 idempotency_key_reuse.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://superx.mintlify.app/_mintlify/api/og/v2?division=Datasets\u0026amp;title=Collect+an+audience+into+a+dataset\u0026amp;description=Collect+the+repliers%2C+quote+posters+or+reposters+of+a+post%2C+the%0Amembers+of+a+public+X+list%2C+or+the+account%27s+own+posts+or+replies%2C%0Ainto+a+stored+dataset+you+can\u0026amp;theme=4e9a0bdaa172d4dfc537fe9f\u0026amp;signature=67da5df0e193d87818396f384c400ab5a10fcfa90012a039cc49b19d2a1baebd\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/superx/Ohz_C_TMxE84ikvK/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"SuperX\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#F4503B\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.superx.so/api-reference/datasets/collect-an-audience-into-a-dataset\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/datasets/collect-an-audience-into-a-dataset.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.superx.so/#organization\",\"name\":\"SuperX\",\"url\":\"https://docs.superx.so\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/superx/ZOrKRYsYXbBhitoI/logo/light.svg?fit=max\u0026auto=format\u0026n=ZOrKRYsYXbBhitoI\u0026q=85\u0026s=d465c38938c34f6ab75cfc50d0039be2\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.superx.so#website\",\"name\":\"SuperX\",\"url\":\"https://docs.superx.so\",\"publisher\":{\"@id\":\"https://docs.superx.so/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.superx.so/api-reference/datasets/collect-an-audience-into-a-dataset#webpage\",\"url\":\"https://docs.superx.so/api-reference/datasets/collect-an-audience-into-a-dataset\",\"name\":\"Collect an audience into a dataset\",\"description\":\"Collect the repliers, quote posters or reposters of a post, the members of a public X list, or the account's own posts or replies, into a stored dataset you can then read, export, or copy into a contact list. source: \\\"research\\\" is the exception: instead of walking an audience it reads people's recent posts and writes a short outreach brief for each one (what they do, what they are building, recent topics, personalization hooks that QUOTE their real posts, and an opener angle). Give it exactly one source - handles, list_id, agent_id or dataset_id - plus optional focus, title and max_rows (1-25, default 10). The briefs land as an ordinary dataset, so GET /v1/datasets/{id}/rows, /export and /contacts read them unchanged. More than 5 profiles research in the background and answer 202. If none of them could be researched, the answer is 200 with data: null, the reasons in meta.skipped, and every credit returned. This endpoint can answer before the work is finished. A small collection runs inside the request and answers 200 with a ready dataset. A big one, or one whose size cannot be established up front, answers 202 with a collecting dataset: poll GET /v1/datasets/{id} until status is ready (or failed) before reading its rows. Only one background collection runs per account at a time; a second one gets 409 collection_in_progress. If nothing matched the filters, the response is 200 with data: null and a note: no dataset is created for an empty result, and the daily collection slot is given back. my_posts and my_replies read the account's own synced posts: they take no target, always finish inside the request, and ignore the profile filters (the response note says so rather than dropping them silently). Cost. Every collection counts against a limit of 10 per day for the account, shared with the collections Ask SuperX runs in the app (429 collection_quota_exceeded). Collections that read X also spend the enrichment allowance: one unit for the size estimate, plus the pages the walk is expected to need, all charged before the walk starts so X-RateLimit-Remaining stays honest about work that outlives the response. Own-content collections spend nothing. Research is charged in AI credits, not collections. source: \\\"research\\\" costs a flat 1 credit per profile ACTUALLY researched: profiles that could not be researched come back in meta.skipped and their credits are returned. It spends one of the plan's daily profile-research runs (429 ai_action_limited with scope: \\\"account\\\") and a slice of a platform-wide fair-use ceiling on live-data actions shared by every SuperX account (429 ai_action_limited with scope: \\\"platform\\\"), and it does NOT count against the 10 collections a day. An empty credit pool is 429 ai_credits_exhausted. What was charged comes back in meta.credits_charged and in the X-Credits-* headers on the 200; a background research run settles when it finishes, so its 202 carries neither, and the figure lands on GET /v1/me and your ledger. Datasets created here appear alongside the ones Ask SuperX built, and are kept for 30 days. Send an Idempotency-Key header to make retries safe: the same key with the same body replays the first response with Idempotency-Replayed: true, and the same key with a different body is rejected with 409 idempotency_key_reuse.\",\"dateModified\":\"2026-10-07T18:31:25.686Z\",\"isPartOf\":{\"@id\":\"https://docs.superx.so#website\"},\"breadcrumb\":{\"@id\":\"https://docs.superx.so/api-reference/datasets/collect-an-audience-into-a-dataset#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.superx.so/api-reference/datasets/collect-an-audience-into-a-dataset#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Datasets\",\"item\":\"https://docs.superx.so/api-reference/datasets/list-datasets\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Collect an audience into a dataset\",\"item\":\"https://docs.superx.so/api-reference/datasets/collect-an-audience-into-a-dataset\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.superx.so/api-reference/datasets/collect-an-audience-into-a-dataset#apireference\",\"headline\":\"Collect an audience into a dataset\",\"name\":\"Collect an audience into a dataset\",\"description\":\"Collect the repliers, quote posters or reposters of a post, the members of a public X list, or the account's own posts or replies, into a stored dataset you can then read, export, or copy into a contact list. source: \\\"research\\\" is the exception: instead of walking an audience it reads people's recent posts and writes a short outreach brief for each one (what they do, what they are building, recent topics, personalization hooks that QUOTE their real posts, and an opener angle). Give it exactly one source - handles, list_id, agent_id or dataset_id - plus optional focus, title and max_rows (1-25, default 10). The briefs land as an ordinary dataset, so GET /v1/datasets/{id}/rows, /export and /contacts read them unchanged. More than 5 profiles research in the background and answer 202. If none of them could be researched, the answer is 200 with data: null, the reasons in meta.skipped, and every credit returned. This endpoint can answer before the work is finished. A small collection runs inside the request and answers 200 with a ready dataset. A big one, or one whose size cannot be established up front, answers 202 with a collecting dataset: poll GET /v1/datasets/{id} until status is ready (or failed) before reading its rows. Only one background collection runs per account at a time; a second one gets 409 collection_in_progress. If nothing matched the filters, the response is 200 with data: null and a note: no dataset is created for an empty result, and the daily collection slot is given back. my_posts and my_replies read the account's own synced posts: they take no target, always finish inside the request, and ignore the profile filters (the response note says so rather than dropping them silently). Cost. Every collection counts against a limit of 10 per day for the account, shared with the collections Ask SuperX runs in the app (429 collection_quota_exceeded). Collections that read X also spend the enrichment allowance: one unit for the size estimate, plus the pages the walk is expected to need, all charged before the walk starts so X-RateLimit-Remaining stays honest about work that outlives the response. Own-content collections spend nothing. Research is charged in AI credits, not collections. source: \\\"research\\\" costs a flat 1 credit per profile ACTUALLY researched: profiles that could not be researched come back in meta.skipped and their credits are returned. It spends one of the plan's daily profile-research runs (429 ai_action_limited with scope: \\\"account\\\") and a slice of a platform-wide fair-use ceiling on live-data actions shared by every SuperX account (429 ai_action_limited with scope: \\\"platform\\\"), and it does NOT count against the 10 collections a day. An empty credit pool is 429 ai_credits_exhausted. What was charged comes back in meta.credits_charged and in the X-Credits-* headers on the 200; a background research run settles when it finishes, so its 202 carries neither, and the figure lands on GET /v1/me and your ledger. Datasets created here appear alongside the ones Ask SuperX built, and are kept for 30 days. Send an Idempotency-Key header to make retries safe: the same key with the same body replays the first response with Idempotency-Replayed: true, and the same key with a different body is rejected with 409 idempotency_key_reuse.\",\"url\":\"https://docs.superx.so/api-reference/datasets/collect-an-audience-into-a-dataset\",\"mainEntityOfPage\":{\"@id\":\"https://docs.superx.so/api-reference/datasets/collect-an-audience-into-a-dataset#webpage\"},\"dateModified\":\"2026-10-07T18:31:25.686Z\",\"publisher\":{\"@id\":\"https://docs.superx.so/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.superx.so#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"SuperX\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"SuperX","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/introduction"}]},{"tab":"API Reference","groups":[{"group":"Identity","pages":[{"title":"Get the key owner","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/me","href":"/api-reference/identity/get-the-key-owner"},{"title":"List your accounts","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/accounts","href":"/api-reference/identity/list-your-accounts"}]},{"group":"Content","pages":[{"title":"List published posts","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/posts","href":"/api-reference/content/list-published-posts"},{"title":"List replies you sent","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/replies","href":"/api-reference/content/list-replies-you-sent"}]},{"group":"Analytics","pages":[{"title":"Get analytics","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/posts/analytics","href":"/api-reference/analytics/get-analytics"}]},{"group":"Scheduling","pages":[{"title":"Write post drafts in your voice","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/posts/draft","href":"/api-reference/scheduling/write-post-drafts-in-your-voice"},{"title":"Rewrite a post in your voice","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/posts/remix","href":"/api-reference/scheduling/rewrite-a-post-in-your-voice"},{"title":"List drafts and scheduled posts","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/scheduled-posts","href":"/api-reference/scheduling/list-drafts-and-scheduled-posts"},{"title":"Create a draft or scheduled post, or publish now","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/scheduled-posts","href":"/api-reference/scheduling/create-a-draft-or-scheduled-post-or-publish-now"},{"title":"Retime queued posts in bulk","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/scheduled-posts/bulk/retime","href":"/api-reference/scheduling/retime-queued-posts-in-bulk"},{"title":"Enable auto retweet on queued posts in bulk","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/scheduled-posts/bulk/auto-retweet","href":"/api-reference/scheduling/enable-auto-retweet-on-queued-posts-in-bulk"},{"title":"Delete queued posts in bulk","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/scheduled-posts/bulk/delete","href":"/api-reference/scheduling/delete-queued-posts-in-bulk"},{"title":"Delete a draft or scheduled post","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml delete /v1/scheduled-posts/{id}","href":"/api-reference/scheduling/delete-a-draft-or-scheduled-post"},{"title":"Edit a draft or scheduled post","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml patch /v1/scheduled-posts/{id}","href":"/api-reference/scheduling/edit-a-draft-or-scheduled-post"},{"title":"List plug templates","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/plug-templates","href":"/api-reference/scheduling/list-plug-templates"}]},{"group":"Tools","pages":[{"title":"Edit one selected piece of a post","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/tools/inline-edit","href":"/api-reference/tools/edit-one-selected-piece-of-a-post"},{"title":"Rewrite a post one preset way","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/tools/rephrase","href":"/api-reference/tools/rewrite-a-post-one-preset-way"},{"title":"Check a statement against a web search","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/tools/factcheck","href":"/api-reference/tools/check-a-statement-against-a-web-search"},{"title":"Score a draft against this account's own posts","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/posts/viral-score","href":"/api-reference/tools/score-a-draft-against-this-accounts-own-posts"},{"title":"Sort recent posts on a topic into Read, Pass or Not sure","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/posts/triage","href":"/api-reference/tools/sort-recent-posts-on-a-topic-into-read-pass-or-not-sure"}]},{"group":"Audience","pages":[{"title":"List replies you received","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/replies/received","href":"/api-reference/audience/list-replies-you-received"},{"title":"Read an audience list","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/audience/{kind}","href":"/api-reference/audience/read-an-audience-list"},{"title":"List engaged contacts","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/contacts","href":"/api-reference/audience/list-engaged-contacts"},{"title":"Get one contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/contacts/{id}","href":"/api-reference/audience/get-one-contact"},{"title":"List one contact's replies to you","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/contacts/{id}/replies","href":"/api-reference/audience/list-one-contacts-replies-to-you"},{"title":"List notes on a contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/contacts/{id}/notes","href":"/api-reference/audience/list-notes-on-a-contact"},{"title":"Add a note to a contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/contacts/{id}/notes","href":"/api-reference/audience/add-a-note-to-a-contact"},{"title":"Delete a note on a contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml delete /v1/contacts/{id}/notes/{noteId}","href":"/api-reference/audience/delete-a-note-on-a-contact"},{"title":"Edit a note on a contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml patch /v1/contacts/{id}/notes/{noteId}","href":"/api-reference/audience/edit-a-note-on-a-contact"}]},{"group":"Inspiration","pages":[{"title":"Search the inspiration library","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/inspiration","href":"/api-reference/inspiration/search-the-inspiration-library"},{"title":"Search the inspiration media index","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/inspiration/media","href":"/api-reference/inspiration/search-the-inspiration-media-index"}]},{"group":"Contact Lists","pages":[{"title":"List contact lists","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/contact-lists","href":"/api-reference/contact-lists/list-contact-lists"},{"title":"Create a contact list","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/contact-lists","href":"/api-reference/contact-lists/create-a-contact-list"},{"title":"Delete a contact list","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml delete /v1/contact-lists/{id}","href":"/api-reference/contact-lists/delete-a-contact-list"},{"title":"Rename a contact list","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml patch /v1/contact-lists/{id}","href":"/api-reference/contact-lists/rename-a-contact-list"},{"title":"List contact list members","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/contact-lists/{id}/members","href":"/api-reference/contact-lists/list-contact-list-members"},{"title":"Add a contact list member","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/contact-lists/{id}/members","href":"/api-reference/contact-lists/add-a-contact-list-member"},{"title":"Remove a contact list member","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml delete /v1/contact-lists/{id}/members/{memberId}","href":"/api-reference/contact-lists/remove-a-contact-list-member"},{"title":"Add contact list members in bulk","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/contact-lists/{id}/members/bulk","href":"/api-reference/contact-lists/add-contact-list-members-in-bulk"},{"title":"Remove contact list members in bulk","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/contact-lists/{id}/members/bulk-delete","href":"/api-reference/contact-lists/remove-contact-list-members-in-bulk"}]},{"group":"Signals","pages":[{"title":"List signal agents","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/signals/agents","href":"/api-reference/signals/list-signal-agents"},{"title":"Create a signal agent","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/signals/agents","href":"/api-reference/signals/create-a-signal-agent"},{"title":"Delete a signal agent","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml delete /v1/signals/agents/{id}","href":"/api-reference/signals/delete-a-signal-agent"},{"title":"Update a signal agent","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml patch /v1/signals/agents/{id}","href":"/api-reference/signals/update-a-signal-agent"},{"title":"Add a signal to an agent","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/signals/agents/{id}/signals","href":"/api-reference/signals/add-a-signal-to-an-agent"},{"title":"Remove a signal from an agent","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml delete /v1/signals/agents/{id}/signals/{signalId}","href":"/api-reference/signals/remove-a-signal-from-an-agent"},{"title":"Set feedback on a lead","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/signals/leads/{id}/feedback","href":"/api-reference/signals/set-feedback-on-a-lead"},{"title":"Search for leads on X now","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/signals/leads/search","href":"/api-reference/signals/search-for-leads-on-x-now"},{"title":"List signal leads","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/signals/leads","href":"/api-reference/signals/list-signal-leads"},{"title":"Suggest keyword watches","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/signals/keywords/suggest","href":"/api-reference/signals/suggest-keyword-watches"},{"title":"Expand an audience description into a rubric","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/signals/icp/expand","href":"/api-reference/signals/expand-an-audience-description-into-a-rubric"},{"title":"Build an audience profile from a website","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/signals/icp/expand-from-url","href":"/api-reference/signals/build-an-audience-profile-from-a-website"}]},{"group":"Engage","pages":[{"title":"List Engage feeds","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/engage/feeds","href":"/api-reference/engage/list-engage-feeds"},{"title":"Create an Engage feed","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/engage/feeds","href":"/api-reference/engage/create-an-engage-feed"},{"title":"Delete an Engage feed","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml delete /v1/engage/feeds/{id}","href":"/api-reference/engage/delete-an-engage-feed"},{"title":"Update an Engage feed","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml patch /v1/engage/feeds/{id}","href":"/api-reference/engage/update-an-engage-feed"},{"title":"Get posts from an Engage feed","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/engage/feeds/{id}/posts","href":"/api-reference/engage/get-posts-from-an-engage-feed"},{"title":"Get mentions of the account","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/engage/mentions","href":"/api-reference/engage/get-mentions-of-the-account"},{"title":"Draft one reply to a post","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/engage/reply-draft","href":"/api-reference/engage/draft-one-reply-to-a-post"}]},{"group":"Media","pages":[{"title":"Presign an image upload","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/media","href":"/api-reference/media/presign-an-image-upload"}]},{"group":"Workers","pages":[{"title":"List Workers","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/workers","href":"/api-reference/workers/list-workers"},{"title":"List Worker suggestions","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/workers/suggestions","href":"/api-reference/workers/list-worker-suggestions"},{"title":"Save a suggestion as a draft","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/workers/suggestions/{id}/draft","href":"/api-reference/workers/save-a-suggestion-as-a-draft"},{"title":"Schedule a suggestion","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/workers/suggestions/{id}/schedule","href":"/api-reference/workers/schedule-a-suggestion"},{"title":"Dismiss a suggestion","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/workers/suggestions/{id}/dismiss","href":"/api-reference/workers/dismiss-a-suggestion"}]},{"group":"Context","pages":[{"title":"Get context settings","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/context","href":"/api-reference/context/get-context-settings"},{"title":"Update context settings","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml patch /v1/context","href":"/api-reference/context/update-context-settings"},{"title":"Replace the product list","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml put /v1/context/products","href":"/api-reference/context/replace-the-product-list"},{"title":"Remove one product","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml delete /v1/context/products/{id}","href":"/api-reference/context/remove-one-product"},{"title":"Add or edit one product","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml patch /v1/context/products/{id}","href":"/api-reference/context/add-or-edit-one-product"},{"title":"Rebuild the generated style guide","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/context/style-guide/regenerate","href":"/api-reference/context/rebuild-the-generated-style-guide"},{"title":"Refresh a product from its page","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/context/products/{id}/scrape","href":"/api-reference/context/refresh-a-product-from-its-page"}]},{"group":"DMs","pages":[{"title":"Queue a DM campaign","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/dm/campaigns","href":"/api-reference/dms/queue-a-dm-campaign"},{"title":"Read one DM campaign","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/dm/campaigns/{id}","href":"/api-reference/dms/read-one-dm-campaign"},{"title":"Cancel a campaign's unsent messages","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml delete /v1/dm/campaigns/{id}","href":"/api-reference/dms/cancel-a-campaigns-unsent-messages"},{"title":"List the DM queue","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/dm/queue","href":"/api-reference/dms/list-the-dm-queue"},{"title":"DM allowances and usage","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/dm/limits","href":"/api-reference/dms/dm-allowances-and-usage"}]},{"group":"Queue","pages":[{"title":"Get queue settings","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/queue-settings","href":"/api-reference/queue/get-queue-settings"},{"title":"Update queue settings","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml patch /v1/queue-settings","href":"/api-reference/queue/update-queue-settings"}]},{"group":"Tags","pages":[{"title":"List tags","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/tags","href":"/api-reference/tags/list-tags"},{"title":"Create a tag","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/tags","href":"/api-reference/tags/create-a-tag"},{"title":"Delete a tag","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml delete /v1/tags/{id}","href":"/api-reference/tags/delete-a-tag"},{"title":"Rename or recolor a tag","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml patch /v1/tags/{id}","href":"/api-reference/tags/rename-or-recolor-a-tag"}]},{"group":"Articles","pages":[{"title":"List articles","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/articles","href":"/api-reference/articles/list-articles"},{"title":"Create an article draft","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/articles","href":"/api-reference/articles/create-an-article-draft"},{"title":"Get an article","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/articles/{id}","href":"/api-reference/articles/get-an-article"},{"title":"Delete an article","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml delete /v1/articles/{id}","href":"/api-reference/articles/delete-an-article"},{"title":"Edit an article","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml patch /v1/articles/{id}","href":"/api-reference/articles/edit-an-article"},{"title":"Publish an article to X now","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/articles/{id}/publish","href":"/api-reference/articles/publish-an-article-to-x-now"},{"title":"Schedule or reschedule an article","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/articles/{id}/schedule","href":"/api-reference/articles/schedule-or-reschedule-an-article"},{"title":"Unschedule an article","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/articles/{id}/unschedule","href":"/api-reference/articles/unschedule-an-article"},{"title":"Generate an AI cover image","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/articles/{id}/cover","href":"/api-reference/articles/generate-an-ai-cover-image"},{"title":"List saved cover styles","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/cover-styles","href":"/api-reference/articles/list-saved-cover-styles"}]},{"group":"Datasets","pages":[{"title":"List datasets","description":"The audience collections Ask SuperX built for the key owner in the\napp: the repliers, quoters or reposters of a post, the members of an\nX list, the owner's own posts or replies, or a research brief.\nNewest first, expired datasets excluded.\n\nDatasets belong to the person, not to one X account, so there is no\n`account_id` parameter here. The account a collection ran as is\nreported as `x_account_id`.\n\nDatasets are kept for 30 days and are created in the SuperX app for\nnow; this API reads them and can copy the people in one into a\ncontact list.\n","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/datasets","href":"/api-reference/datasets/list-datasets"},{"title":"Collect an audience into a dataset","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/datasets","href":"/api-reference/datasets/collect-an-audience-into-a-dataset"},{"title":"Get a dataset","description":"One dataset's status, counts and coverage.\n\nEvery status answers 200, so this is the endpoint to poll while a\ncollection runs: `collecting` carries live `progress`, `failed`\ncarries a `failure_note`, and `ready` carries the honest `coverage`\nsentence and the `filters` the collection applied. The counts on a\ncollecting dataset are not final.\n","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/datasets/{id}","href":"/api-reference/datasets/get-a-dataset"},{"title":"Get dataset rows","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/datasets/{id}/rows","href":"/api-reference/datasets/get-dataset-rows"},{"title":"Export a dataset as CSV","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/datasets/{id}/export","href":"/api-reference/datasets/export-a-dataset-as-csv"},{"title":"Add a dataset's people to a contact list","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/datasets/{id}/contacts","href":"/api-reference/datasets/add-a-datasets-people-to-a-contact-list"},{"title":"Draft outreach messages onto a research dataset","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/datasets/{id}/outreach-drafts","href":"/api-reference/datasets/draft-outreach-messages-onto-a-research-dataset"},{"title":"Refine a dataset by what each person wrote","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/datasets/{id}/refine","href":"/api-reference/datasets/refine-a-dataset-by-what-each-person-wrote"}]},{"group":"X Lookups","pages":[{"title":"Look up one public post live","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/x/posts/{id}","href":"/api-reference/x-lookups/look-up-one-public-post-live"},{"title":"Top replies to a public post","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/x/posts/{id}/replies","href":"/api-reference/x-lookups/top-replies-to-a-public-post"},{"title":"Look up one public profile live","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/x/users/{handle}","href":"/api-reference/x-lookups/look-up-one-public-profile-live"},{"title":"Latest posts of a public account","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/x/users/{handle}/posts","href":"/api-reference/x-lookups/latest-posts-of-a-public-account"}]},{"group":"Meta","pages":[{"title":"Machine-readable quickstart","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/docs","href":"/api-reference/meta/machine-readable-quickstart"}]}]}]},"basePath":"","title":"Collect an audience into a dataset - SuperX","buildId":"dpl_9VVk5y1P8k1ATeJguVngy9Q3cmbD","deploymentId":"dpl_9VVk5y1P8k1ATeJguVngy9Q3cmbD","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-DX1Meug0.js","utils-B_OMIQVC.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-ChxhRPMa.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-CuKvD8Iv.js","snippetPresets-C5d7p2hp.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-CfHcE8m4.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-C1zZV314.js","shallow-CmQhqCJn.js","getApiPlaygroundDisplay-YRo9s1O7.js","CodeSnippet-RN1MTdfk.js","CodeSnippets-DKLPHxJA.js","Page-BAvA99GL.js","getPastedJson-bz0M41mU.js","icon-CsmhpPrv.js","MethodPill-CNGsVE77.js","DuplicateIcon-DilfU_Z2.js","createIcon-BdsYzQck.js","DynamicMarkdown-CbqEDjbV.js","SectionHeading-O6hXpFCN.js","axios-vUo_bRtp.js","Markdown-nKm-uidQ.js","clsx-ClVdStUn.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-CIQkMg3R.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-ImrFS4Fy.js"]}