SOURCE_ID: search_x_tweets NAME: Search X Tweets CATEGORY: Signals Run a one-time search of public X (Twitter) posts matching a query, with the same language / account / media / engagement filters as the ongoing monitor. Creates a static source that imports a fixed batch of matching posts once and makes them available to your Floqer workflows. Use it for snapshots; use `track_x_posts` when you need ongoing monitoring. INDEX: 1. Endpoints 2. Search model 3. Lifecycle (one-time 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): `search_x_tweets`. POST /api/v1/sources/search_x_tweets/preview Scope: sources:read Returns a sample page (up to ~10) of matching X posts for the given body, without creating anything. Does not consume Floqer credits. POST /api/v1/sources/search_x_tweets Scope: sources:write Creates the source and starts a one-time import of up to `max_tweets` posts. Returns `source_instance_id` (the new source's UUID). The import 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 the imported rows. `` = UUID from Create. Body: { workflow_id, field_mapping, push_existing?, run? }. Source-agnostic; see concepts.txt §10. No connection is required. There is no dynamic-options endpoint for this source today (see §6). Because this is a one-time source, there is no ongoing-status PATCH to pause/resume. ================================================================================ 2. SEARCH MODEL ================================================================================ Every preview/create call searches public X posts. Core behaviour: - Query: `search_terms` is required — a single X search query string supporting keywords, quoted phrases, `from:handle`, hashtags, and boolean operators. - Sort: `sort_by` is required. Accepted values: Top most relevant / popular posts first Latest newest posts first Pass exactly "Top" or "Latest" (case-sensitive). - Batch size: `max_tweets` sets how many posts the one-time import pulls (required on create). Preview always returns a small sample (up to ~10), independent of `max_tweets`. - Optional filters narrow the result set: language, verified / X-Blue accounts, media type, and minimum engagement (see §5). ================================================================================ 3. LIFECYCLE (ONE-TIME ONLY) ================================================================================ Search X Tweets is a one-time (static) source. On create it pulls up to `max_tweets` matching posts once and stores them — there is no schedule, no `expiration_date`, and no recurring re-check. max_tweets (create only) Required on create. Positive number. Total posts to import. Credit cost scales with `max_tweets`. Ignored on preview (preview caps at ~10). To refresh the data, create a new source. ================================================================================ 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" max_tweets optional on preview: defaults to 10 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 Create accepts: search_terms required: non-empty string sort_by required: "Top" or "Latest" max_tweets required: positive number start_date optional 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": "snowflake hiring", "sort_by": "Top", "only_verified_users": true } Example create body: { "name": "Snowflake hiring snapshot", "search_terms": "snowflake hiring", "sort_by": "Top", "max_tweets": 200, "only_verified_users": true } Preview response envelope: { "status": 200, "data": { "data": [ { ...post row... } ], "metadata": { "total_results": 10 } } } Create response envelope: { "status": 201, "data": { "source_instance_id": "", "name": "Snowflake hiring snapshot", "created_at": "2026-05-27T12:00:00.000Z" } } The import runs asynchronously — Create returns as soon as the source is created and the import is started, not when posts have finished arriving. ================================================================================ 5. FIELD CATALOGUE ================================================================================ search_terms (string) — required The X search query. Supports keywords, quoted phrases, boolean operators, `from:handle`, hashtags, etc. sort_by (string) — required Sort order. Accepted values: "Top" (relevant first) or "Latest" (newest first). Case-sensitive. max_tweets (number) — required on create, optional on preview Number of posts to import. Positive number. Credit cost scales with this value. Preview ignores it and returns up to ~10. tweet_language (string) — optional Restrict to a single language by ISO code (e.g. "en"). only_verified_users (boolean) — optional Only posts from verified accounts. only_twitter_blue (boolean) — optional Only posts from X-Blue (paid verified) accounts. only_quote (boolean) — optional Only quote posts. only_image (boolean) — optional Only posts containing an image. only_video (boolean) — optional Only posts containing a video. minimum_retweets (number) — optional Only posts with at least this many reposts. minimum_replies (number) — optional Only posts with at least this many replies. start_date (string) — optional Earliest post date to include. YYYY-MM-DD or ISO-like. 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/search_x_tweets/options/` endpoint. ================================================================================ 7. HOW TO CONFIGURE END-TO-END ================================================================================ Step 1 — Preview before committing POST /api/v1/sources/search_x_tweets/preview Body: { "search_terms": "...", "sort_by": "Top", ...filters } Inspect the returned `data[]` rows. Preview never creates anything and does not consume credits. Step 2 — Create the source POST /api/v1/sources/search_x_tweets Body: + `"name"` and `"max_tweets"`. 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`). See concepts.txt §10. This is a one-time import — once it finishes there are no further runs. To get fresh data, create a new source. ================================================================================ 8. KEY NOTES ================================================================================ - No connection is required. - One-time import: no schedule, no `expiration_date`, no pause/resume. - Preview returns up to ~10 posts and does not consume credits — credits are consumed by the create import only, scaling with `max_tweets`. - `sort_by` is required; pass exactly "Top" or "Latest". - `max_tweets` is required on create and optional (defaults to 10) on preview. ================================================================================ 9. WHEN TO USE ================================================================================ - One-off research: pull a fixed batch of posts about a topic, event, or competitor for analysis. - Seed a list: import matching authors once, then enrich and score them in a workflow. - Snapshot before a campaign: capture current conversation around a launch keyword. When you instead want continuous monitoring of new matching posts, use the `track_x_posts` source. ================================================================================ Last updated: 2026-06-02. Reference: https://floqer.com/docs/reference