> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Does a successful empty timeline mean the API is broken?

> A succeeded twitter.web.fetch_search_timeline response with data.timeline: [] indicates zero returned posts for that page rather than an API failure; verify HTTP status, error, and request_id first.

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.

```python
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?

| State                                                                | Next action                                                                                                                                                              |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `empty_timeline`                                                     | Review 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_timeline`                                                    | Export the saved page locally. Running the collection request again would purchase page one a second time.                                                               |
| `http_failure` or `reported_failure`                                 | Inspect 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_array` | Recover 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_ids`   | Preserve 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](/guides/x-search-posts) · [Latest versus Top](/faq/x-search-order) · [X questions](/faq/x)

Contract reference: `data:twitter.web.fetch_search_timeline`.