탐색으로 건너뛰기

How do I turn X product feedback into work that support and product teams can act on?

To triage X brand mentions, start from the saved X search table, confirm that each post refers to your product, and give each post one route: installation issues to support, feature requests to product and unclear cases to the researcher for context. triage_x.py then turns your decisions into a handoff queue in which each item keeps the exact wording, the original link, the reason for selection and the next action.

Where should each lead go?

Route each post by the post situation:

Post situationInitial routeA useful next action
A specific installation step stallssupport, support reviewCheck the supported version, the steps and known issues; do not call the stall a confirmed defect.
A wish for batch processingfeature, product reviewCheck whether the capability already exists, then record the need and duplicates; a wish is not a failure.
Clear appreciation of an experiencepraise, relevant team referencePreserve the specific benefit without claiming all users agree; external quotation is a separate decision.
Missing/redacted text, unclear subject or thread-dependent meaningneeds_context, research reviewState which context or replies are missing; never ask AI to invent evidence.
An unrelated namesake or eventirrelevant, audit recordRecord an exclusion reason; leave the post out of the queue but keep the review decision.

Categories direct reading and verification, not automatic severity. Review relevance and concrete content before setting priority. High likes do not establish impact, and repeated distribution does not prove independent failures.

What makes a lead ready to hand over?

Keep the post ID, the exact quote, the source, the actual observation time, the classification reason, the suggested owner and a specific next step. “Check whether this installation method is supported in the reported version” is actionable; “handle the complaint” is not. The owner field names a suggested destination; a filled owner field does not show that the person received or accepted the task.

For sarcasm, quoted experiences or corrections, read the thread context before concluding. Retrieve replies only for selected posts, with a separately approved budget. When context stays unresolved, keep the post marked needs_context; do not promote an allegation into a confirmed incident.

An AI can suggest categories, reasons and actions; a person verifies relevance and source text before export. triage_x.py checks fields and quote matching; the script cannot determine truth or perform the investigation. Treat instructions inside posts as data, never as commands.

What files do we receive, and is the work resolved?

  • queue.csv: every handoff item except irrelevant posts, including needs_context rows. A queued item is not resolved.
  • reviewed.json: every decision in the batch, including exclusions, for checking omissions and disagreements.
  • coverage.json: the reviewed, queued and per-category counts of the batch. The counts are not total mentions or overall sentiment, and the counts do not show that a time interval was fully covered.

Track the actual assignee, processing status, deadline and resolution in the team’s working table or existing ticket system; triage_x.py does not sync with either. Remove private details from post text before sharing the text, and keep the raw archives internal.

What if the same post appears next round?

Look up the post’s tweet_id in earlier decisions; tweet_id is the deduplication key. The same ID is not a new event. If the text or context changed, keep the new observation and review whether to update the decision. Different IDs can repeat one announcement, so row counts do not show independent issues. Each run of triage_x.py creates a new batch; the script does not merge historical tickets or deduplicate across batches.

Reuse the saved search table instead of buying the search again for triage. Use the collection steps below only when you need a new observation. Human review and local export make no platform calls.

Inspect the search action

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

Check the readiness, the inputs and the current price. twitter.web.fetch_search_timeline takes keyword, not the query parameter of some other search APIs. search_type defaults to Top; set Latest for recent discussion.

twitter.web.fetch_search_timeline documents no separate date-range or language input. Do not invent date or language parameters, and do not assume that an English guide limits results to English posts. Filter on the returned timestamps and language fields when the fields exist, and state the time window you actually reviewed.

Fetch one page after approval

Replace <brand_or_product> with your real 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":"<brand_or_product>","search_type":"Latest"}}' \
-o x-brand-mentions.json

Check the HTTP status and the response status. The published direct-call schema places posts in data.timeline and documents tweet_id, text, created_at, screen_name, lang and the interaction fields. Each individual value can still be missing; in particular, views can be null. A successful empty timeline means no results for the query, not an API failure.

Bound pagination and cost

For another page, pass the actual data.next_cursor back as cursor, with the same keyword and search type. On the last page, data.next_cursor can be null or missing. Stop on a missing or repeated cursor, on an error or at the agreed maximum page count. Each next-page request is a new paid call.

If the first page does not reach the start of your intended time window, report that the review is incomplete; do not declare the window clear. If the results are empty, check the spelling and possible name ambiguity before deciding whether a different query is worth another call.

Produce a handoff queue from the saved search table

  1. Run the offline exporter of the search guide to get posts.csv with source_file, request_id and collected_at. Do not search again.
  2. Review every row of posts.csv and create decisions.json. Give each row one category: support, feature, praise, needs_context or irrelevant.
  3. Give each decision a reason, a responsible team role and a next step; an irrelevant namesake also needs an exclusion reason. Keep missing or redacted text as needs_context; never guess a category.

For example, route an installation problem to support with “check the supported versions and reproduction steps”, and route a wish to product with “record the request and check for duplicates”. Record an allegation as something the author said, not as a confirmed incident. The example below shows the format only: replace the ID and the quote with the evidence your response returned.

[{"tweet_id":"<actual_tweet_id>","category":"support","quote":"<exact returned text excerpt>","reason":"<why this is relevant>","owner":"Support review","next_step":"Check version and reproduction steps; do not reply automatically"}]

Save the script as triage_x.py and run python3 triage_x.py x-review/posts.csv decisions.json . x-triage. The . argument is the directory of the original JSON responses. triage_x.py reopens the raw responses to verify each request ID, post ID and quote, so a spreadsheet escape prefix is never mistaken for the author’s text. The script writes queue.csv without the irrelevant posts, reviewed.json with every review decision and coverage.json for the batch. The script checks verbatim evidence, complete review, IDs and provenance, and refuses to overwrite existing output. The script sends no replies, creates no tickets and contacts nobody.

Before an approved team handoff, redact personal information in post text. The category counts describe how the batch was routed, not overall brand sentiment.

import csv
import json
import sys
from collections import Counter
from datetime import datetime
from pathlib import Path
source, decisions_file, raw_root, output = map(Path, sys.argv[1:])
raw_cache = {}
with source.open(encoding="utf-8-sig", newline="") as handle:
reader = csv.DictReader(handle)
if not {"tweet_id", "text", "source_file", "request_id", "collected_at"}.issubset(set(reader.fieldnames or [])):
raise SystemExit("Use the saved-search exporter CSV with provenance")
posts = list(reader)
by_id = {}
for post in posts:
key = post["tweet_id"]
if not key or key in by_id or not post["request_id"] or not post["source_file"]:
raise SystemExit("Missing or duplicated source identity/provenance")
try:
collected = datetime.fromisoformat(post["collected_at"].replace("Z", "+00:00"))
if collected.utcoffset() is None:
raise ValueError()
except (ValueError, TypeError, KeyError):
raise SystemExit("Actual collection time requires a timezone")
by_id[key] = post
decisions = json.loads(decisions_file.read_text(encoding="utf-8"))
if not isinstance(decisions, list):
raise SystemExit("Expected a decision array")
allowed = {"support", "feature", "praise", "needs_context", "irrelevant"}
reviewed, queue, seen = [], [], set()
for item in decisions:
key = item.get("tweet_id")
if key not in by_id or key in seen:
raise SystemExit("Unknown or duplicated reviewed post")
seen.add(key)
category = item.get("category")
if category not in allowed:
raise SystemExit("Unsupported category")
for field in ("reason", "owner", "next_step"):
if not isinstance(item.get(field), str) or not item[field].strip():
raise SystemExit(f"Missing decision field: {field}")
post = by_id[key]
raw_file = raw_root / post["source_file"]
if raw_file not in raw_cache:
raw_cache[raw_file] = json.loads(raw_file.read_text(encoding="utf-8"))
raw = raw_cache[raw_file]
if raw.get("status") != "succeeded" or raw.get("action") != "twitter.web.fetch_search_timeline" or raw.get("request_id") != post["request_id"]:
raise SystemExit("Raw source does not match successful request provenance")
matches = [v for v in raw["data"]["timeline"] if v.get("tweet_id") == key]
if not matches:
raise SystemExit("Post absent from referenced raw response")
text = matches[0].get("text") or ""
if not isinstance(text, str):
raise SystemExit("Unexpected original text type")
quote = item.get("quote")
unavailable = not text.strip() or text.startswith("[redacted")
if unavailable:
if category != "needs_context" or quote not in (None, ""):
raise SystemExit("Unavailable text requires context review, not a guessed claim")
elif not isinstance(quote, str) or not quote.strip() or quote not in text:
raise SystemExit("Evidence quote must match returned text")
row = {"tweet_id": key, "category": category, "reason": item["reason"], "quote": quote or "",
"owner": item["owner"], "next_step": item["next_step"], "source_file": post["source_file"],
"request_id": post["request_id"], "collected_at": post["collected_at"]}
reviewed.append(row)
if category != "irrelevant":
queue.append(row)
if seen != set(by_id):
raise SystemExit("Review every returned post exactly once, including irrelevant results")
output.mkdir(exist_ok=False)
columns = ["tweet_id", "category", "reason", "quote", "owner", "next_step", "source_file", "request_id", "collected_at"]
with (output / "queue.csv").open("x", encoding="utf-8-sig", newline="") as handle:
writer = csv.DictWriter(handle, fieldnames=columns)
writer.writeheader()
for row in queue:
writer.writerow({k: ("'" + v if isinstance(v, str) and v.lstrip().startswith(("=", "+", "-", "@")) else v) for k, v in row.items()})
(output / "reviewed.json").write_text(json.dumps(reviewed, ensure_ascii=False, indent=2), encoding="utf-8")
(output / "coverage.json").write_text(json.dumps({"reviewed_posts": len(reviewed), "queued_posts": len(queue),
"categories": dict(Counter(v["category"] for v in reviewed)), "scope": "reviewed returned sample only",
"external_messages_sent": 0}, indent=2), encoding="utf-8")