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. INDEX: 1. Endpoints 2. Search model 3. Lifecycle (ongoing only) 4. Body shape (preview + create) 5. Field catalogue 6. Dynamic options 7. How to configure end-to-end 8. Key notes 9. When to use ================================================================================ 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