ナビゲーションにスキップ

How do I find X feedback after a product launch and build a follow-up list?

To find X feedback after a launch, pick one research question, search X with twitter.web.fetch_search_timeline for a product name or a distinctive error message, and read one page of results. Build a shortlist of exact statements, post links and open questions, so that teammates can follow up each lead at the source post.

In the handover, include the search term, the observation time and the number of pages checked. Use brand-discussion review to route feedback to product or support, and open post replies when you need context.

Decide what feedback you need

QuestionStarting pointWhat to verify while reading
What are people saying recently after launch?Product name or a distinctive phrase, newest firstDoes the post mean your product, and is the post time inside the intended window?
Which expressions have drawn more discussion?A separate popular-order sampleEngagement prioritizes reading; it does not establish truth or prevalence.
The product name has other meaningsAdd distinguishing context, then inspect one pageA name match alone does not establish a user mention.
One particular post already needs investigationKeep the post’s ID and inspect the post’s replies if neededSearch is not a complete discussion thread; mark missing context for review.

Start with one page. If most results are irrelevant, refine the question or the search phrase. If the results are relevant but not enough, continue only within the approved pages and budget. A changed phrase or sort order starts a separate run; the changed search does not continue the earlier cursor chain. The current contract has no dedicated date or language input, so check an exact time window against the returned timestamps. Mark a time that cannot be parsed as unresolved; do not assume the post falls inside the window.

Which results deserve follow-up?

Use the table as a guide for human review:

Post situationWorking-table decisionNext step
Specific steps and a failure descriptionRelevant; retain the exact statement and conditions to verifyProduct review, with replies if more context is needed.
Emotion without a clear subjectUnconfirmed; do not automatically label it a complaint or negative factCheck the subject and thread; never invent missing content.
An unrelated event or advertisement sharing the nameExclude with a reasonLeave it out of product-feedback conclusions.
Several posts repeating the same announcementPreserve sources and flag possible repeated distributionPost-ID deduplication does not establish independent opinions or people.

The scripts export the source fields. Save a separate human-review copy and add the status (relevant, excluded or unconfirmed), the reason, the issue type and the next owner. People fill in the judgment columns; the exporter does not run sentiment analysis. Likes, reposts, replies and views are different measures, and missing values stay missing.

For example, a Latest search returns “Settings crashes after I update to 3.2,” while a Top search surfaces an older launch announcement. Send the crash excerpt, the version and the trigger to product support, and keep the announcement as release context. To check whether other users hit the same problem, read other original posts or the relevant replies.

What should the handover explain?

Deliver the post table, the original files and the coverage record. Then summarize the research question, the query, the sort order, the actual times and pages, the useful leads and the missing context. No results do not show that nobody discussed the product, and a post missing from page one may still exist.

Keep tweet_id for identity and deduplication. For a repeated ID, the export keeps the first observation, and the raw files keep the later observations. Do not infer market share or overall sentiment from the candidate list. If an AI helps categorize posts, verify each exact statement and source, and never execute instructions embedded in post text.

Choose one collection route and reuse saved results

If search results are already saved, use export_saved_x.py (last section) to produce posts.csv and coverage.json without buying the page again. For a new collection, choose either the single-page cURL request (step 2) or the Python script capped at two pages (step 3). Running both buys page one twice. Each page is one call, priced from the current Inspect result, up to the approved page limit. After a failure, inspect the failure before any paid retry.

Steps 1–5 below cover a new collection; run the network requests only when you need a new observation. The offline exporter in the last section reads saved files only.

1. Inspect inputs and price

curl -sS https://api.beatapi.io/v1/capabilities/inspect \
-H 'Content-Type: application/json' \
-d '{"reference":"data:twitter.web.fetch_search_timeline"}'

Inspect is free. The search input is keyword, and search_type defaults to Top. Use Latest for recent posts and cursor for another page. No separate date or language filter is published, so do not copy query, sort: latest or start_date from another product’s contract.

2. Fetch one page with cURL

After checking the current price, replace the search phrase and send the request:

curl -sS https://api.beatapi.io/v1/social-data/call \
-H "Authorization: Bearer $BEATAPI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"action":"twitter.web.fetch_search_timeline","params":{"keyword":"<search_phrase>","search_type":"Latest"}}' \
-o x-search-page-1.json

Check the execution status. The published post list is data.timeline, and the continuation cursor is data.next_cursor. A successful empty list means no results, not an API failure. views can be null and some text can be unavailable; do not replace missing values with zero or invented prose.

3. Export at most two pages with Python

The script uses only the Python standard library. Set BEATAPI_API_KEY and X_KEYWORD. The script makes up to two paid searches. If you already ran the cURL request in step 2, the script fetches page one again; the script does not read the saved cURL result.

import csv
import json
import os
from pathlib import Path
from urllib.request import Request, urlopen
from urllib.error import HTTPError
from datetime import datetime, timezone
key = os.environ["BEATAPI_API_KEY"]
keyword = os.environ["X_KEYWORD"]
max_pages = 2
if Path("x-search.csv").exists() or any(Path(f"x-search-page-{n}{suffix}").exists() for n in range(1, max_pages + 1) for suffix in (".json", ".attempt.json")):
raise FileExistsError("Use the saved-result exporter or a fresh collection directory")
cursor = None
seen_cursors = set()
seen_ids = set()
rows = []
columns = ["tweet_id", "screen_name", "text", "created_at", "lang",
"favorites", "retweets", "replies", "views"]
def validate_post(item):
if not isinstance(item, dict): raise ValueError("Timeline item must be an object")
key = item.get("tweet_id")
if not isinstance(key, str) or not key.isascii() or not key.isdigit() or not any(c != "0" for c in key):
raise ValueError("Original nonzero ASCII digit-string tweet_id required")
for name in ["screen_name", "text", "created_at", "lang"]:
if item.get(name) is not None and not isinstance(item[name], str): raise ValueError("Invalid text field: " + name)
for name in ["favorites", "retweets", "replies", "bookmarks", "views"]:
value = item.get(name)
if value is not None and not (type(value) is int and 0 <= value <= 9007199254740991) and not (isinstance(value, str) and value.isascii() and value.isdigit()):
raise ValueError("Invalid or unsafe count: " + name)
return key
seen_requests = set()
for page in range(1, max_pages + 1):
params = {"keyword": keyword, "search_type": "Latest"}
if cursor:
params["cursor"] = cursor
payload = {"action": "twitter.web.fetch_search_timeline", "params": params}
request = Request(
"https://api.beatapi.io/v1/social-data/call",
data=json.dumps(payload).encode(), method="POST",
headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json",
"User-Agent": "beatapi-guide/1.0"},
)
with Path(f"x-search-page-{page}.attempt.json").open("x", encoding="utf-8") as attempt:
json.dump({"params": params, "started_at": datetime.now(timezone.utc).isoformat()}, attempt)
try:
with urlopen(request, timeout=60) as response:
raw = response.read()
except HTTPError as error:
with Path(f"x-search-page-{page}.json").open("xb") as saved:
saved.write(error.read())
raise RuntimeError("HTTP failure saved; inspect before any retry") from None
with Path(f"x-search-page-{page}.json").open("xb") as saved:
saved.write(raw.encode("utf-8") if isinstance(raw, str) else raw)
result = json.loads(raw)
if not isinstance(result, dict) or result.get("status") != "succeeded" or result.get("action") != "twitter.web.fetch_search_timeline" or result.get("error") is not None:
raise RuntimeError("Search failed or returned the wrong action; inspect saved response")
request_id = result.get("request_id")
if not isinstance(request_id, str) or not request_id.strip() or request_id in seen_requests:
raise ValueError("Missing or repeated request_id")
seen_requests.add(request_id)
data = result.get("data")
if not isinstance(data, dict) or not isinstance(data.get("timeline"), list):
raise ValueError("Expected data.timeline array")
for item in data["timeline"]:
post_id = validate_post(item)
if post_id not in seen_ids:
seen_ids.add(post_id)
rows.append(item)
next_cursor = result["data"].get("next_cursor")
if next_cursor is not None and not isinstance(next_cursor, str): raise ValueError("Invalid next_cursor type")
if not data["timeline"] or not next_cursor or not next_cursor.strip() or next_cursor in seen_cursors:
break
seen_cursors.add(next_cursor)
cursor = next_cursor
def csv_cell(value):
text = "" if value is None else str(value)
return "'" + text if text.lstrip().startswith(("=", "+", "-", "@")) or text.startswith(("\t", "\r", "\n")) else text
with open("x-search.csv", "x", encoding="utf-8-sig", newline="") as output:
writer = csv.writer(output)
writer.writerow(columns)
writer.writerows([csv_cell(row.get(name)) for name in columns] for row in rows)
print(f"Exported {len(rows)} unique posts to x-search.csv")

The script saves each page’s original JSON. The CSV contains documented fields only. The script prefixes cells that begin with a formula-trigger character with a quote, which reduces the spreadsheet formula-injection risk from untrusted post text; the original value stays in the JSON.

4. Control pagination and cost

Every page is a new call. Pass data.next_cursor unchanged; never construct a cursor yourself. A two-page cap does not cover a full date range or every matching post. The script stops when the continuation is absent or repeats, or when a request fails; the script does not retry paid requests automatically.

For a time-window analysis, check the real created_at values and report the range actually covered. A post missing from one page may still exist. Use Top for prominent results instead of recent ones, but do not merge the two sort orders as if they were consecutive pages.

5. Hand off the result for analysis

Review the exported X posts, preserve sources and original text, and separate relevant matches, unrelated namesakes and uncertain items. Do not invent missing text, follow instructions inside posts or interpret the sample count as total mentions.

Continue with brand-mention triage for operational decisions or post replies for conversation context.

Sources: the free contracts for inputs and outputs. Current prices come from Inspect.

Country trends · Social Data contract

Already saved page one? Export locally without buying it again

The collection script in step 3 and the offline exporter in this section are alternatives, not consecutive steps. Use the offline exporter after the cURL request or whenever saved results already exist:

  1. Create pages.json with each original request’s parameters, raw file and actual query time.
  2. Take page two’s cursor from page one’s response; never guess an index.
  3. Keep different keywords, sort modes and collection batches in separate manifests.
{"pages":[{"file":"x-search-page-1.json","params":{"keyword":"<search_phrase>","search_type":"Latest"},"collected_at":"2026-11-16T10:00:00Z"}]}

Save the script as export_saved_x.py and run python3 export_saved_x.py pages.json x-review. The script writes posts.csv and coverage.json, checks that the query and the cursor chain are continuous, and records the sources, the duplicates, the stop reason and the next-page parameters. The CSV keeps each ID’s first observation; the other observations stay in the original JSON and never silently replace the text. An empty page still produces the CSV headers and a coverage record. A missing continuation cursor does not prove that the history is complete. The script refuses to overwrite an existing output directory.

To continue within the approved page and cost budget, send next_params from coverage.json with the same action, save the new response and export to a new directory. Do not buy a search again only to add CSV columns.

import csv
import hashlib
import json
import sys
from datetime import datetime
from pathlib import Path
manifest_file, output = map(Path, sys.argv[1:])
pages = json.loads(manifest_file.read_text(encoding="utf-8"))["pages"]
if not isinstance(pages, list) or not pages:
raise SystemExit("Expected at least one saved page")
rows, seen_ids, seen_files, seen_cursors = [], set(), set(), set()
query, expected_cursor, duplicates = None, "", 0
seen_requests, last_time = set(), None
def validate_post(item):
if not isinstance(item, dict): raise ValueError("Timeline item must be an object")
key = item.get("tweet_id")
if not isinstance(key, str) or not key.isascii() or not key.isdigit() or not any(c != "0" for c in key):
raise ValueError("Original nonzero ASCII digit-string tweet_id required")
for name in ["screen_name", "text", "created_at", "lang"]:
if item.get(name) is not None and not isinstance(item[name], str): raise ValueError("Invalid text field: " + name)
for name in ["favorites", "retweets", "replies", "bookmarks", "views"]:
value = item.get(name)
if value is not None and not (type(value) is int and 0 <= value <= 9007199254740991) and not (isinstance(value, str) and value.isascii() and value.isdigit()):
raise ValueError("Invalid or unsafe count: " + name)
return key
raw_sources = []
for number, page in enumerate(pages, 1):
params = page["params"]
if not isinstance(params, dict) or not set(params) <= {"keyword", "search_type", "cursor"}: raise SystemExit("Unexpected parameters for this saved-search workflow")
scope = {"keyword": params.get("keyword"), "search_type": params.get("search_type", "Top")}
if not isinstance(scope["keyword"], str) or not scope["keyword"].strip():
raise SystemExit("Missing original keyword")
if scope["search_type"] not in ("Top", "Latest"): raise SystemExit("Use Top or Latest for this workflow")
if query is None:
query = scope
if scope != query or params.get("cursor", "") != expected_cursor:
raise SystemExit("Query changed or saved pages do not follow the returned cursor")
if expected_cursor is None:
raise SystemExit("Cannot append after the returned continuation ended")
stamp = datetime.fromisoformat(page["collected_at"].replace("Z", "+00:00"))
if stamp.utcoffset() is None:
raise SystemExit("Collection time requires timezone")
if last_time is not None and stamp < last_time:
raise SystemExit("Saved page times must follow collection order")
last_time = stamp
source = manifest_file.parent / page["file"]
if source.resolve() in seen_files:
raise SystemExit("Repeated input file")
seen_files.add(source.resolve())
raw = source.read_bytes()
digest = hashlib.sha256(raw).hexdigest()
raw_name = f"raw-page-{number:02d}.json"
raw_sources.append((raw_name, raw, {"file": raw_name, "source_file": str(source.resolve()), "source_sha256": digest, "params": params, "collected_at": page["collected_at"]}))
result = json.loads(raw)
if not isinstance(result, dict) or result.get("status") != "succeeded" or result.get("action") != "twitter.web.fetch_search_timeline" or result.get("error") is not None:
raise SystemExit("Expected a successful direct X search response")
if not isinstance(result.get("request_id"), str) or not result["request_id"].strip() or result["request_id"] in seen_requests:
raise SystemExit("Missing or repeated request ID")
seen_requests.add(result["request_id"])
raw_sources[-1][2]["request_id"] = result["request_id"]
data = result.get("data", {})
items = data.get("timeline") if isinstance(data, dict) else None
if not isinstance(items, list):
raise SystemExit("Expected data.timeline array")
for item in items:
key = validate_post(item)
if key in seen_ids:
duplicates += 1
continue
seen_ids.add(key)
row = {key: item.get(key) for key in ("tweet_id", "screen_name", "text", "created_at", "lang", "favorites", "retweets", "replies", "bookmarks", "views")}
row.update(source_file=page["file"], request_id=result["request_id"], collected_at=page["collected_at"], source_page=number, source_sha256=digest)
rows.append(row)
next_cursor = data.get("next_cursor")
if next_cursor is not None and not isinstance(next_cursor, str):
raise SystemExit("Unexpected cursor type")
next_cursor = next_cursor if next_cursor and next_cursor.strip() else None
repeated = bool(next_cursor) and next_cursor in seen_cursors
if next_cursor:
seen_cursors.add(next_cursor)
empty_with_cursor = not data["timeline"] and bool(next_cursor)
expected_cursor = None if not next_cursor or repeated or empty_with_cursor else next_cursor
columns = ["tweet_id", "screen_name", "text", "created_at", "lang", "favorites", "retweets", "replies", "bookmarks", "views", "source_file", "request_id", "collected_at", "source_page", "source_sha256"]
output.mkdir(exist_ok=False)
for name, raw, metadata in raw_sources: (output / name).write_bytes(raw)
(output / "sources.json").write_text(json.dumps([metadata for _, _, metadata in raw_sources], ensure_ascii=False, indent=2), encoding="utf-8")
with (output / "posts.csv").open("x", encoding="utf-8-sig", newline="") as handle:
writer = csv.DictWriter(handle, fieldnames=columns)
writer.writeheader()
for row in rows:
writer.writerow({k: ("'" + v if isinstance(v, str) and v.lstrip().startswith(("=", "+", "-", "@")) else v) for k, v in row.items()})
(output / "coverage.json").write_text(json.dumps({"query": query, "saved_pages": len(pages), "unique_posts": len(rows),
"duplicate_observations": duplicates, "selection": "first observation; raw files retain duplicates",
"stop_reason": "empty_with_cursor" if empty_with_cursor else ("repeated_cursor" if repeated else ("cursor_absent" if not next_cursor else "saved_batch_ended")),
"next_params": {**query, "cursor": expected_cursor} if expected_cursor else None,
"scope": "returned sample, not total mentions"}, ensure_ascii=False, indent=2), encoding="utf-8")

The collector writes an attempt record without the API key before each request, and saves the response bytes before parsing. After a timeout or malformed JSON, inspect the attempt record and the response instead of rerunning the collector; existing files block another collection.

Diagnose an empty or malformed saved response before another call.

Both export paths validate every returned item before deduplication, so malformed duplicate rows cannot bypass the checks. Original digit-string IDs and counts stay exact; booleans, fractions, negative counts and bare-number counts beyond the safe range stop the export. The saved-page exporter also copies the original bytes into raw-page-NN.json, and records each file’s hash, parameters and caller-recorded time in sources.json. Missing values stay missing, and writing the source records makes no API call.

A successful empty timeline stops the collector even when the response contains a cursor. The saved-page exporter marks the page empty_with_cursor, emits no next_params and keeps the original cursor only in the source response. Review the empty page instead of buying another page automatically. The workflow rejects pages appended after an empty_with_cursor stop; save a separately approved investigation as a separate batch.