SOURCE_ID: track_x_posts NAME: Track X Posts CATEGORY: Signals Monitor public X (Twitter) posts that match a search query — optionally narrowed by language, account type, media, and engagement thresholds. Creates an ongoing source that re-checks for new matching posts on a schedule until a stop date. Imported post rows become available to your Floqer workflows for social listening, brand monitoring, and lead capture. 1. ENDPOINTS Source identifier (used in every endpoint path): `track_x_posts`. POST /api/v1/sources/track_x_posts/preview Scope: sources:read Returns a sample page (up to ~10) of matching X posts for the given body, without creating anything. Use this to validate the query and filters and inspect row shape. Does not consume Floqer credits. POST /api/v1/sources/track_x_posts Scope: sources:write Creates an ongoing source, runs an immediate first fetch, and schedules recurring checks. Returns `source_instance_id` (the new source's UUID). Each fetch consumes Floqer credits. GET /api/v1/sources//data Scope: sources:read Paginated rows imported into the created source. `` is the UUID returned by Create. Query: `page_no` (default 1), `page_size` (default 20, max 200). Source-agnostic; see concepts.txt §10. POST /api/v1/sources//sync Scope: sources:write Connects the created source to a workflow and (by default) backfills it with current rows. `` = UUID from Create. Body: { workflow_id, field_mapping, push_existing?, run? }. Source-agnostic; see concepts.txt §10. PATCH /api/v1/sources//status Scope: sources:write Pause or resume an ongoing source. Body: {"status": "active"|"paused"}. A paused source stops scheduling new checks until resumed. No connection is required. There is no dynamic-options endpoint for this source today (see §6). 2. SEARCH MODEL Every preview/create call searches public X posts. Core behaviour: - Query: `search_terms` is required — a single X search query string. It supports the same operators X search supports (keywords, quoted phrases, `from:handle`, `#hashtag`, etc.). - Sort: `sort_by` is required. Accepted values: Top most relevant / popular posts first Latest newest posts first `sort_by` is matched case-sensitively; pass exactly "Top" or "Latest". - Optional filters narrow the result set: language, verified / X-Blue accounts, media type, and minimum engagement (see §5). Preview returns the most recent / top matching posts directly. 3. LIFECYCLE (ONGOING ONLY) Track X Posts is always an ongoing source — there is no one-time mode (for a one-time snapshot use `search_x_tweets`). expiration_date (create only) Required on create. Date string (YYYY-MM-DD or any ISO-like value). The source stops scheduling new checks after this date. Accepted but ignored on preview. frequency (create only) Optional. Interval in days between scheduled checks. Defaults to 1 (daily) when omitted. Must be a positive number. Accepted but ignored on preview. start_date (optional) Optional date string. Sets the earliest post date the monitor begins tracking from. On create the source runs an immediate first fetch and then re-checks on the `frequency` schedule until `expiration_date`. Each scheduled run imports only posts newer than the last run, so the same post is never imported twice. Discovered posts are appended and pushed to connected workflows automatically. 4. BODY SHAPE (PREVIEW + CREATE) Field names are snake_case. Unknown top-level keys are rejected with 400 — the body is strict. Preview accepts: search_terms required: non-empty string (the X search query) sort_by required: "Top" or "Latest" start_date optional: valid date string tweet_language optional: ISO language code (e.g. "en") only_verified_users optional: boolean only_twitter_blue optional: boolean only_quote optional: boolean only_image optional: boolean only_video optional: boolean minimum_retweets optional: number minimum_replies optional: number expiration_date accepted but ignored on preview (create-only) frequency accepted but ignored on preview (create-only) Create accepts: search_terms required: non-empty string sort_by required: "Top" or "Latest" expiration_date required: valid date string frequency optional: positive number (days); defaults to 1 start_date optional: valid date string tweet_language optional only_verified_users optional only_twitter_blue optional only_quote optional only_image optional only_video optional minimum_retweets optional minimum_replies optional name required: display name for the new source Example preview body: { "search_terms": "\"data warehouse\" OR snowflake", "sort_by": "Latest", "tweet_language": "en", "only_verified_users": true, "minimum_retweets": 5 } Example create body: { "name": "Snowflake mentions (verified)", "search_terms": "\"data warehouse\" OR snowflake", "sort_by": "Latest", "tweet_language": "en", "only_verified_users": true, "minimum_retweets": 5, "expiration_date": "2026-09-01", "frequency": 1 } Preview response envelope: { "status": 200, "data": { "data": [ { ...post row... } ], "metadata": { "total_results": 10 } } } Rows are plain key/value objects (see §5). Preview returns a small sample (up to ~10 posts). Create response envelope: { "status": 201, "data": { "source_instance_id": "", "name": "Snowflake mentions (verified)", "created_at": "2026-05-27T12:00:00.000Z" } } The initial fetch runs asynchronously — Create returns as soon as the source is created and the first fetch is started. 5. FIELD CATALOGUE search_terms (string) — required The X search query. Supports keywords, quoted phrases, boolean operators, `from:handle`, hashtags, etc. Example: "snowflake", "\"Series A\" from:techcrunch" sort_by (string) — required Sort order of matching posts. Accepted values: Top most relevant / popular first Latest newest first Pass the value exactly (case-sensitive). tweet_language (string) — optional Restrict to a single language by ISO code (e.g. "en", "es", "fr"). only_verified_users (boolean) — optional Only include posts from verified accounts. only_twitter_blue (boolean) — optional Only include posts from X-Blue (paid verified) accounts. only_quote (boolean) — optional Only include quote posts. only_image (boolean) — optional Only include posts containing an image. only_video (boolean) — optional Only include posts containing a video. minimum_retweets (number) — optional Only include posts with at least this many reposts. minimum_replies (number) — optional Only include posts with at least this many replies. start_date (string) — optional Earliest post date the monitor tracks from. YYYY-MM-DD or ISO-like. expiration_date (string) — required on create only Stop monitoring after this date. Accepted but ignored on preview. frequency (number) — optional, create only Days between scheduled checks. Positive number; defaults to 1 (daily). Accepted but ignored on preview. name (string) — required on create only Human-readable display name for the source. Imported row fields (read-only — returned by preview and stored on create): uid / id Post ID (unique per post) url Direct link to the post on X text Full post text retweet_count Repost count reply_count Reply count like_count Like count quote_count Quote count view_count View count created_at Post timestamp media Attached media (images / video), when present author_name Author display name author_id Author account ID author_username Author @handle author_url Author profile URL author_profile_picture Author avatar URL author_cover_picture Author banner URL author_description Author bio author_is_blue_verified Whether the author is X-Blue verified author_location Author location text author_followers Author follower count author_following Author following count 6. DYNAMIC OPTIONS None. `sort_by` has a fixed two-value set ("Top" / "Latest") documented in §5; all other fields are free-form. There is no `POST /api/v1/sources/track_x_posts/options/` endpoint. 7. HOW TO CONFIGURE END-TO-END Step 1 — Preview before committing POST /api/v1/sources/track_x_posts/preview Body: { "search_terms": "...", "sort_by": "Latest", ...filters } Inspect the returned `data[]` rows. Iterate until happy — preview never creates anything and does not consume credits. Step 2 — Create the source POST /api/v1/sources/track_x_posts Body: + `"name"`, `"expiration_date"`, and optionally `"frequency"`. Response: { "status": 201, "data": { "source_instance_id": "", ... } } Step 2b — (Optional) Poll imported posts after create GET /api/v1/sources//data?page_no=1&page_size=20 ( = UUID from Step 2) Step 3 — Sync the source into a workflow POST /api/v1/sources//sync ( = UUID from Step 2 ) Map workflow inputs to row fields (common: `input.text`, `input.url`, `input.author_username`, `input.author_name`, `input.author_url`). See concepts.txt §10. The source keeps checking on the `frequency` schedule until `expiration_date`. New posts discovered on each run are appended and pushed to connected workflows automatically. 8. KEY NOTES - No connection is required. There is no "connect first" gate. - Preview returns a small sample (up to ~10 posts) and does not consume credits — credits are consumed per fetch only after create. - `sort_by` is required; pass exactly "Top" or "Latest". - Scheduled runs import only posts newer than the previous run, so the same post is never imported twice. - `frequency` defaults to 1 (daily) when omitted on create. - If credit consumption fails during a scheduled run, the source may be paused. Top up credits and resume to continue. 9. WHEN TO USE - Brand / competitor monitoring: track mentions of your product or a rival and route them to a workflow for sentiment scoring or alerting. - Lead capture from social: watch for buying-intent phrases and enrich the authors as inbound leads. - Verified-voice listening: combine `only_verified_users` with engagement thresholds to surface high-signal posts only. - Topic tracking: monitor a hashtag or phrase with daily `frequency` and a 90-day `expiration_date`. When you instead want a one-time snapshot of tweets matching a query rather than an ongoing monitor, use the `search_x_tweets` source. Last updated: 2026-06-02. Reference: https://floqer.com/docs/reference