While building Xquik, I learned that a Twitter API integration must do more than search tweets.
It must paginate Twitter search results, run durable Twitter scraper jobs, and make Twitter automation safe to retry.
A demo needs one successful request. Production needs confidence in every result.
Search needs completion signals. Extraction needs durable state. Automatic Twitter posting needs safe retry rules.
This post covers the three contracts I now consider essential: A cursor and coverage contract for Twitter search. A job contract for Twitter scraping and data extraction. An event and action contract for Twitter automation.
The examples use patterns implemented in Xquik. The same principles apply to other APIs and internal systems. Twitter Search Needs a Completion Contract
A useful Twitter search API needs four things: Stable string identifiers Opaque pagination cursors An explicit has-more signal Coverage information for complex collections
The client should never calculate or modify a cursor. Pass it back exactly as received.
The client should also avoid treating an empty page as completion. Filtering can produce an empty page while another cursor still exists.
The contract header enables normalized response fields. List responses use hasmore and nextcursor.
Store X identifiers as strings. JavaScript cannot safely represent every large numeric identifier.
The query can contain normal X search syntax. Structured filters can cover authors, dates, languages, media, and engagement.
That makes advanced Twitter search easier to generate from application inputs. It also avoids fragile string concatenation.
A cursor can tell you another page exists. It cannot prove that one timeline exposed every relevant item.
A conversation can contain direct replies, nested branches, and several rankings. One timeline may omit part of that structure.
Useful coverage fields include: The source-reported reply count The number of collected replies The strategies attempted Cursor or branch failures Whether the coverage threshold passed
Xquik returns a failure when complete-reply coverage remains too low. It does not label that result complete.
Silent partial data is worse than an explicit error. It enters databases, reports, and models as if it were complete. A Twitter Scraper API Needs a Job Contract