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

Does a successful empty timeline mean the API is broken?

No. A successful twitter.web.fetch_search_timeline response with data.timeline: [] means that search page returned zero posts, not that the API failed. Check the HTTP status and status field first, then verify data.timeline. If data.timeline is missing or the request failed, inspect the full response and request_id. When a brand or product-model query returns an empty timeline, check spelling and filters first and run any simpler query as a separate search.

Diagnose the response you already saved

  1. Use the complete direct response from /v1/social-data/call, not a shortened AI preview.
  2. Read the actual HTTP status code from the saved response headers.
  3. Save the script below as diagnose_x_search.py.
  4. Run python3 diagnose_x_search.py x-search-page-1.json 200 diagnosis.json, replacing 200 with the actual HTTP status.

diagnose_x_search.py sends no requests, leaves the original response file unchanged, and writes only the new diagnosis.json. The state printed by diagnose_x_search.py classifies the saved response rather than confirming a successful collection.

import hashlib
import json
import sys
from pathlib import Path
source, http_text, target = sys.argv[1:]
http = int(http_text)
if not 100 <= http <= 599: raise ValueError('Use the actual HTTP status from the saved headers')
source, target = Path(source), Path(target)
raw = source.read_bytes()
report = {'http_status': http, 'source_file': str(source.resolve()), 'source_sha256': hashlib.sha256(raw).hexdigest(),
'network_calls': 0, 'automatic_retry': False, 'next_page_executed': False}
try:
result = json.loads(raw)
except (ValueError, UnicodeDecodeError):
result = None
if http != 200:
report.update(state='http_failure', next_step='Inspect saved HTTP headers and error; do not classify this as an empty search')
elif not isinstance(result, dict):
report.update(state='unreadable_response', next_step='Keep the original bytes; obtain the full direct JSON, not an HTML page or preview')
elif result.get('status') == 'failed' or result.get('error') is not None:
report.update(state='reported_failure', next_step='Inspect the actual error code and request ID before any separately approved retry')
elif result.get('status') != 'succeeded' or result.get('action') != 'twitter.web.fetch_search_timeline':
report.update(state='wrong_response', next_step='Use the successful direct response of twitter.web.fetch_search_timeline')
elif not isinstance(result.get('request_id'), str) or not result['request_id'].strip():
report.update(state='missing_request_id', next_step='Keep the response; source identity is missing')
else:
data = result.get('data')
items = data.get('timeline') if isinstance(data, dict) else None
if not isinstance(items, list):
report.update(state='missing_timeline_array', next_step='Do not substitute an absent or redacted field with []; inspect the original shape')
elif data.get('next_cursor') is not None and not isinstance(data['next_cursor'], str):
report.update(state='invalid_cursor', next_step='Retain the posts but do not invent or follow a cursor')
else:
invalid = []
ids = []
for n, item in enumerate(items):
value = item.get('tweet_id') if isinstance(item, dict) else None
if not isinstance(value, str) or not value.isascii() or not value.isdigit() or not any(c != '0' for c in value):
invalid.append(n)
else:
ids.append(value)
if invalid:
report.update(state='unusable_timeline_ids', invalid_item_indices=invalid, next_step='Keep raw items; a missing, numeric or redacted ID is not an empty result')
else:
report.update(state='empty_timeline' if not items else 'usable_timeline', returned_items=len(items), unique_ids=len(set(ids)),
has_nonblank_cursor=bool((data.get('next_cursor') or '').strip()),
next_step='Review the original phrase and search_type; do not repeat or paginate automatically' if not items else 'Use the saved-page exporter without purchasing page one again')
if isinstance(result, dict):
error = result.get('error')
error = error if isinstance(error, dict) else {}
request_id = result.get('request_id') or error.get('request_id')
if isinstance(request_id, str) and request_id.strip(): report['request_id'] = request_id
if isinstance(error.get('code'), str): report['error_code'] = error['code']
with target.open('x', encoding='utf-8') as f:
json.dump(report, f, ensure_ascii=False, indent=2)
print(report['state'])

What should I do with the diagnosis?

StateNext action
empty_timelineReview the exact saved keyword and search_type. Record zero returned rows for that query at that time; do not conclude that total mentions are zero.
usable_timelineExport the saved page locally. Running the collection request again would purchase page one a second time.
http_failure or reported_failureInspect the actual headers, error code, and request_id. Resolve the authentication, balance, rate-limit, or service error reported by the error code before any retry.
unreadable_response, wrong_response, or missing_timeline_arrayRecover the full direct result and fix the input file. Purchasing more pages does not repair a truncated wrapper or parser mismatch.
missing_request_id, invalid_cursor, or unusable_timeline_idsPreserve the raw response for troubleshooting. Do not invent identifiers, turn placeholders into text, or construct a continuation token manually.

diagnose_x_search.py validates the response envelope, the data.timeline array, and usable tweet_id strings. diagnose_x_search.py does not evaluate post accuracy or every metric field; field-level export checks belong to the CSV exporter in the search guide. source_sha256 in diagnosis.json links the report to the local response bytes and is not a signed server receipt.

Should I simplify the query or switch to Latest?

Check the exact saved request before changing any parameter. The search phrase goes in keyword, and search_type defaults to Top. Latest requests recent ordering rather than guaranteeing complete results or coverage of a specific date range. Modify the query only when you can identify a concrete fix such as a misspelling, an incorrect brand name, or an unintended extra filter. Record the original zero-row observation separately from the revised query, keeping each run’s settings and collection time distinct.

Every changed phrase, changed search_type, or next page is a separate paid request. Check the current price of data:twitter.web.fetch_search_timeline at /v1/capabilities/inspect before approving another call, and avoid automatically trying multiple query variants just to obtain a nonempty page. If an empty page still returns a cursor, diagnosis.json records has_nonblank_cursor; diagnose_x_search.py does not follow that cursor, and the next page may also return zero matches.

Saved-page CSV export · Latest versus Top · X questions

Contract reference: data:twitter.web.fetch_search_timeline.