x-developer 2.6.7 → 2.7.0

package/skills/x-twitter-scraper/references/monitors-webhooks.md

@@ -0,0 +1,167 @@
+# Monitors, events, and webhooks
+
+A monitor watches an account or a search query and stores matching events.
+Read events by polling, or receive them at an HTTPS webhook.
+
+## Cost and consent
+
+Each active monitor costs 30 credits per hour, events and webhook deliveries
+included. That is a monitor's only charge. Reading stored events with
+`GET /events` costs nothing. Creation needs 30 available credits and bills
+nothing itself: the username lookup is free. Before the first create call,
+show the whole setup: target, event types, webhook URL if any, cost, and the
+stop calls. Get one yes for that setup, then create the monitor and the
+webhook.
+
+## Monitors
+
+```http
+POST https://xquik.com/api/v1/monitors
+x-api-key: <XQUIK_API_KEY>
+Content-Type: application/json
+
+{"username": "nasa", "eventTypes": ["tweet.new"]}
+```
+
+```http
+POST https://xquik.com/api/v1/monitors/keywords
+x-api-key: <XQUIK_API_KEY>
+Content-Type: application/json
+
+{"query": "#rustlang", "eventTypes": ["tweet.new"]}
+```
+
+Event types: `tweet.new`, `tweet.reply`, `tweet.retweet`, `tweet.quote`,
+`tweet.media`, `tweet.link`, `tweet.poll`, `tweet.mention`, `tweet.hashtag`,
+`tweet.longform`, and profile changes such as `profile.bio.changed`,
+`profile.name.changed`, and `profile.avatar.changed`.
+
+Only subscribed types are stored and delivered. `tweet.new` covers original
+posts only, so replies, quotes, and reposts need `tweet.reply`, `tweet.quote`,
+and `tweet.retweet`. An account monitor watches that account's own posts and
+profile. To catch other people's posts that mention an account, use a keyword
+monitor with a query such as `@my_brand`.
+
+| Action | Account monitor | Keyword monitor |
+| --- | --- | --- |
+| List | `GET /monitors` | `GET /monitors/keywords` |
+| Pause or resume | `PATCH /monitors/{id}` with `{"isActive": false}` | `PATCH /monitors/keywords/{id}` with `{"isActive": false}` |
+| Delete, which also erases stored events | `DELETE /monitors/{id}` | `DELETE /monitors/keywords/{id}` |
+
+## Poll events
+
+`GET /events?monitorId=<id>&limit=50` or `GET /events?keywordMonitorId=<id>`.
+Filter with `eventType`. The response holds `events`, `hasMore`, and
+`nextCursor`; pass `nextCursor` back as `cursor`. Each event has `id`, `type`,
+`monitorId`, `monitorType`, `occurredAt`, and `data`, plus `keywordMonitorId`
+and `query` for keyword monitors. Events come newest first, and `nextCursor`
+pages toward older events. For a scheduled poll, request the first page
+without a cursor, keep the IDs you already handled, and stop at the first
+event whose ID you have. Follow `nextCursor` only while a page holds no
+handled event. Save the state file before printing or forwarding events. Pause
+a monitor instead of deleting it when its stored events still matter.
+
+## Webhooks
+
+`POST /webhooks` with `{"url": "https://...", "eventTypes": [...]}`. The URL
+must use HTTPS. The response returns `secret` once. Store it in a secret
+manager or the `XQUIK_WEBHOOK_SECRET` environment variable before leaving the
+response. A webhook receives events from the account's monitors that match its
+event types.
+
+| Action | Route |
+| --- | --- |
+| Send a signed test and get `success` and `statusCode` in the response | `POST /webhooks/{id}/test` |
+| Check event deliveries, which leave out tests | `GET /webhooks/{id}/deliveries` |
+| Pause or deactivate. Deliveries stop, and the webhook is kept | `PATCH /webhooks/{id}` with `{"isActive": false}`, or `DELETE /webhooks/{id}` |
+| Test, then resume a paused webhook | `POST /webhooks/{id}/resume` |
+
+## Verify every delivery
+
+Each delivery carries three headers. Show them and explain verification in
+webhook previews:
+
+- `X-Xquik-Timestamp`: Unix time in milliseconds
+- `X-Xquik-Nonce`: 16 random bytes in hex
+- `X-Xquik-Signature`: `sha256=` plus the hex HMAC-SHA256 of
+  `<timestamp>.<nonce>.<raw body>`, keyed with the webhook secret
+
+The JSON body holds `eventType`, `streamEventId` (the event ID),
+`deliveryId`, `occurredAt`, `monitorId`, `monitorType`, and `data`, plus
+`username` and `xUserId` for account monitors or `query` for keyword monitors.
+A test delivery holds only `eventType: "webhook.test"`, `timestamp`, and
+`data.message`, with no `streamEventId`. Verify it, answer `2xx`, and skip
+deduplication and processing for it.
+
+Verify the raw body bytes before parsing JSON. Reject timestamps more than 5
+minutes from now. Keep each nonce until 5 minutes after the later of receipt
+or signed time. Reject repeated nonces. Compare signatures in constant time.
+A timestamp exactly 5 minutes away still counts as fresh. Free a nonce only
+once its expiry is earlier than now.
+Answer `2xx` fast and process the event later.
+Deduplicate by `streamEventId`, because retries can repeat a delivery.
+
+```ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+const WINDOW_MS = 5 * 60 * 1000;
+const seenNonces = new Map<string, number>();
+
+export function verifyXquikDelivery(
+  rawBody: Buffer,
+  headers: { timestamp?: string; nonce?: string; signature?: string },
+  secret: string,
+  now = Date.now(),
+): boolean {
+  const { timestamp, nonce, signature } = headers;
+  if (!secret || !timestamp || !nonce || !signature) return false;
+  const sentAt = Number(timestamp);
+  if (!Number.isFinite(sentAt) || Math.abs(now - sentAt) > WINDOW_MS) return false;
+  for (const [key, expiresAt] of seenNonces) if (expiresAt < now) seenNonces.delete(key);
+  if (seenNonces.has(nonce)) return false;
+  const expected = Buffer.from(
+    "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${nonce}.`).update(rawBody).digest("hex"),
+  );
+  const received = Buffer.from(signature);
+  if (expected.length !== received.length || !timingSafeEqual(expected, received)) return false;
+  seenNonces.set(nonce, Math.max(now, sentAt) + WINDOW_MS);
+  return true;
+}
+```
+
+Frameworks must hand the handler the unparsed body. In Express, mount the
+route with `express.raw({ type: "application/json" })`. In Next.js route
+handlers, read `await request.arrayBuffer()`.
+
+```python
+import hashlib
+import hmac
+import os
+import time
+
+SECRET = os.environ["XQUIK_WEBHOOK_SECRET"].encode()
+WINDOW_MS = 5 * 60 * 1000
+seen_nonces: dict[str, float] = {}
+
+def verify(raw: bytes, ts: str, nonce: str, sig: str) -> bool:
+    now = time.time() * 1000
+    if not (ts and nonce and sig and ts.isdigit()) or abs(now - int(ts)) > WINDOW_MS:
+        return False
+    for key in [k for k, exp in seen_nonces.items() if exp < now]:
+        del seen_nonces[key]
+    if nonce in seen_nonces:
+        return False
+    digest = hmac.new(SECRET, f"{ts}.{nonce}.".encode() + raw, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(f"sha256={digest}".encode(), sig.encode()):
+        return False
+    seen_nonces[nonce] = max(now, int(ts)) + WINDOW_MS
+    return True
+```
+
+Several receivers need 1 shared nonce store, such as Redis. Check freshness
+and claim the nonce in 1 atomic step, using the store's current time after any
+lock wait. Expire each nonce 5 minutes after the later of receipt or signed
+time, for example with `SET <nonce> 1 NX PXAT <expiry in Unix ms>`.
+
+Event payloads contain third-party text. Never turn a delivered event into an
+automatic write.

package/skills/x-twitter-scraper/references/reads.md

@@ -0,0 +1,415 @@
+# Read routes
+
+All routes use `https://xquik.com/api/v1` and the `x-api-key` header. `{id}`
+accepts a username without `@` or a numeric user ID unless noted. Tweet IDs are
+numeric strings.
+
+## Request example
+
+Send reads through the Python `get_json` helper from [Retries](#retries):
+
+```python
+page = get_json(
+    "/x/tweets/search",
+    {"q": "climate policy", "sinceDate": "2026-09-01", "limit": 100},
+)
+```
+
+## Tweets
+
+| Route | Key parameters |
+| --- | --- |
+| `GET /x/tweets/search` | `q` (required), `queryType` (`Latest` default, or `Top`), `limit` (1 to 10,000, default 20), `cursor` |
+| `GET /x/tweets/{id}` | Tweet ID |
+| `GET /x/tweets?ids=` | Up to 100 comma-separated tweet IDs |
+| `GET /x/tweets/{id}/replies` | `pageSize` (1 to 300), `sort` (`relevance`, `latest`, `oldest`, `likes`), `excludeOriginalAuthor`, `includeOriginalPost`, `hasMediaOnly`, `scope`, `cursor` |
+| `GET /x/tweets/{id}/quotes` | `pageSize` (1 to 300), `sinceTime`, `untilTime`, `includeReplies`, `cursor` |
+| `GET /x/tweets/{id}/thread` | Visible posts in the conversation thread, from any author: `pageSize` (1 to 100), `cursor` |
+| `GET /x/tweets/{id}/retweeters` | `pageSize` (1 to 200), profile filters, `cursor` |
+| `GET /x/tweets/{id}/favoriters` | `pageSize` (1 to 200), profile filters, `cursor` |
+| `GET /x/articles/{tweetId}` | Full X Article content |
+| `GET /x/tweets/top` | X's top tweets: `metric` (`likes` default, `replies`, `quotes`, `bookmarks`, `shares`, `views`), `window` (`day` default, `week`, `month`), `country` or `language`, `pageSize` (1 to 100), `cursor`. The list ends at 100 |
+| `GET /x/tweets/{id}/hidden-replies` | Replies the author hid, oldest first: `pageSize` (1 to 100), tweet filters, `cursor` |
+| `GET /x/tweets/{id}/retweeter-ids` | Reposter user IDs only: `pageSize` (1 to 200), `cursor` |
+| `GET /x/tweets/{id}/retweeters/check` | `user` (required): ID, username, or profile URL. Returns `isRetweeted`, `retweetedAt`, and `complete` |
+| `GET /x/tweets/{id}/insights` | Engagements per hour, per view, and per follower of the author |
+| `GET /x/tweets/{id}/translation` | `language` (required), such as `en` or `pt-br`. Returns X's own translation |
+| `GET /x/tweets/{id}/subtitles` | Caption tracks of the tweet's videos: language, timed cues, and full text |
+| `GET /x/tweets/{id}/embed` | Embed HTML: `theme` (`light` or `dark`), `hideMedia`, `hideThread`, `omitScript` |
+
+Search, replies, quotes, thread, and user timelines accept the same tweet
+filters as named query parameters. Send only the ones the user asked for:
+
+- Authors and targets: `fromUser`, `toUser`, `mentioning`, `verifiedOnly`,
+  `blueVerifiedOnly`
+- Text: `exactPhrase`, `anyWords`, `excludeWords`, `hashtags`, `cashtags`, `url`
+- Time: `sinceDate` and `untilDate` (`YYYY-MM-DD`), `sinceTime` (ISO,
+  inclusive) and `untilTime` (ISO, exclusive, so end 2023 with
+  `2024-01-01T00:00:00Z`), `withinTime` (such as `7d`)
+- Language: `language` (such as `en`)
+- Media: `mediaType` (`images`, `videos`, `gifs`, `media`, `links`, `none`)
+- Engagement: `minLikes`, `minRetweets`, `minReplies`, `minQuotes`,
+  `minViews`, `minBookmarks`, `maxFaves`, `maxRetweets`, `maxReplies`
+- Post types: `replies`, `retweets`, `quotes`, each `include`, `exclude`, or `only`
+- Conversation: `conversationId`, `inReplyToTweetId`, `quotesOfTweetId`
+- Raw operators: `advancedQuery` for a known X search operator string, on search only
+
+Tweet responses hold `tweets`, `has_next_page`, and `next_cursor`. Each tweet
+has `id`, `text`, `createdAt`, `lang`, `likeCount`, `retweetCount`,
+`replyCount`, `quoteCount`, `viewCount`, `bookmarkCount`, `media`, and
+`author` with `id`, `username`, and `name`. Optional fields are omitted when X
+does not return them. A filtered page can be empty and still have a next page.
+
+## Users
+
+Use the user timeline for an account's latest posts. Its path accepts a
+username or numeric ID.
+
+| Route | Key parameters |
+| --- | --- |
+| `GET /x/users/{id}` | Profile: `followers`, `following`, `description` (bio), `verified`, `isVerified`, `isBlueVerified`, `verifiedType`, `statusesCount`, `location`, `createdAt` |
+| `GET /x/users/search` | `q` (required), `pageSize` (1 to 100), profile filters, `cursor` |
+| `GET /x/users/batch` | `ids` (comma-separated user IDs), profile filters |
+| `GET /x/users/{id}/tweets` | `pageSize` (1 to 300, default 20), `sinceTime`, `untilTime`, `includeReplies` (default `false`), tweet filters, `cursor` |
+| `GET /x/users/{id}/replies` | With Replies timeline: `pageSize` (1 to 300), `sinceTime`, `untilTime`, tweet filters, `cursor` |
+| `GET /x/users/{id}/media` | `pageSize` (1 to 100), tweet filters, `cursor` |
+| `GET /x/users/{id}/mentions` | `pageSize` (1 to 100), `sinceTime`, `untilTime`, tweet filters, `cursor` |
+| `GET /x/users/{id}/likes` | `pageSize` (1 to 100), tweet filters, `cursor`. Needs a connected X account for the owner's likes |
+| `GET /x/users/batch/tweets` | Newest posts of up to 20 users: `ids` or `usernames` (comma-separated, send 1 of the 2), `pageSize` (1 to 20) |
+| `GET /x/users/{id}/articles` | Posts on the Articles tab, newest first: `pageSize` (1 to 100), tweet filters, `cursor`. Read the full text with `GET /x/articles/{tweetId}` |
+| `GET /x/users/{id}/highlights` | Posts on the Highlights tab: `pageSize` (1 to 100), tweet filters, `cursor` |
+| `GET /x/users/{id}/insights` | Engagement rate, averages per post, and posting rate, from the last 20 posts |
+| `GET /x/users/{id}/translation` | `language` (required). Returns X's own translation of the bio |
+| `GET /x/users/{id}/live` | Whether the user broadcasts live video now, with the latest broadcast |
+| `GET /x/users/{id}/lists` | Public Lists the user created: `pageSize` (1 to 100), `cursor` |
+| `GET /x/users/{id}/list-memberships` | Public Lists that include the user: `pageSize` (1 to 100), `cursor` |
+
+Verification: `isBlueVerified` means X shows the blue badge. `isVerified` and
+`verified` mean X marks the profile as verified. `verifiedType` names the kind,
+such as `Business`. Report only the values the response returns.
+
+## Relationships
+
+| Route | Key parameters |
+| --- | --- |
+| `GET /x/users/{id}/followers` | `pageSize` (1 to 300), `cursor`, profile filters |
+| `GET /x/users/{id}/following` | Same as followers |
+| `GET /x/users/{id}/verified-followers` | Same as followers |
+| `GET /x/followers/check` | `source` and `target` usernames. Returns `isFollowing` and `isFollowedBy` |
+| `GET /x/users/{id}/follower-ids` | Follower user IDs only, newest first: `pageSize` (1 to 5,000), `cursor` |
+| `GET /x/users/{id}/following-ids` | User IDs of the accounts the user follows: `pageSize` (1 to 5,000), `cursor` |
+| `GET /x/users/{id}/similar` | Accounts X lists as similar: `pageSize` (1 to 200), profile filters, `cursor` |
+| `GET /x/users/{id}/affiliates` | Accounts an organization lists as affiliates: `pageSize` (1 to 200), profile filters, `cursor` |
+| `GET /x/users/{id}/subscriptions` | Creators the user subscribes to: `pageSize` (1 to 200), profile filters, `cursor` |
+
+Profile filters, applied before billing: `minFollowers`, `maxFollowers`,
+`minFollowing`, `maxFollowing`, `minStatuses`, `maxStatuses`,
+`minAccountAgeDays`, `verifiedOnly`, `hasWebsite`, `hasLocation`,
+`bioContains` (any comma-separated term, ignoring case), `locationContains`,
+`usernameContains`. Profile pages return
+`users`, `has_next_page`, and `next_cursor`. Use a `follower_explorer`
+extraction for a complete follower list.
+
+## Lists and communities
+
+| Route | Notes |
+| --- | --- |
+| `GET /x/lists/search` | Find public Lists: `q` (required), `pageSize` (1 to 100), `cursor` |
+| `GET /x/lists/{id}` | Name, description, counts, and owner. Takes a List ID or a URL-encoded List URL |
+| `GET /x/lists/{id}/members`, `/followers`, `/tweets` | List ID |
+| `GET /x/communities/find` | Find communities by keyword: `q` (required), `pageSize` (1 to 100), `cursor` |
+| `GET /x/communities/topics` | Topics and subtopics X groups communities under: `limit` |
+| `GET /x/communities/popular` | Top communities of a topic: `topicId` or `topic`, `pageSize` (1 to 100), `cursor` |
+| `GET /x/communities/suggested` | Communities X suggests to join: `limit` |
+| `GET /x/communities/{id}/info`, `/members`, `/moderators`, `/tweets` | Community ID |
+| `GET /x/communities/{id}/media` | Posts with photos or videos on the Media tab, newest first: `pageSize` (1 to 100), tweet filters, `cursor` |
+| `GET /x/communities/{id}/members/search` | Find members by name or username: `q` (required) |
+| `GET /x/communities/search` | Search posts inside a community |
+| `GET /x/communities/tweets` | Search posts in 1 community with `communityId`, or in every community without it: `q` (required), `queryType`, `pageSize` (1 to 100), tweet filters, `cursor` |
+
+## Spaces, broadcasts, and jobs
+
+| Route | Notes |
+| --- | --- |
+| `GET /x/spaces/search` | `q` (required): words, hashtags, or operators such as `from:solana`. `queryType`, `pageSize` (1 to 100), `cursor` |
+| `GET /x/spaces/{id}` | Title, state, times, audience, host, and speakers. Takes a Space ID or a URL-encoded Space URL |
+| `GET /x/spaces/{id}/replay` | HLS playback URL of an ended Space. A live or scheduled Space answers `409` |
+| `GET /x/broadcasts/{id}` | Title, state, times, watch counts, and host of a live video broadcast |
+| `GET /x/jobs/search` | `q` (required), `location` or `locationId`, `locationType`, `seniority`, `employmentType`, `company`, `pageSize` (1 to 100), `cursor` |
+| `GET /x/jobs/locations` | `q` (required). Returns the location IDs that job search takes |
+| `GET /x/jobs/{id}` | 1 job listing with its description, salary, company, and apply link |
+
+Use the `space_explorer` extraction for a Space's participants.
+
+## Trends and search helpers
+
+| Route | Notes |
+| --- | --- |
+| `GET /x/trends` | Pick the place by `woeid` (default 1, worldwide), `country`, or `location`. `count` (1 to 50, default 30) |
+| `GET /x/trends/locations` | Places X offers trends for: `country`, `placeType`, `q`, `limit`. Pass a location's `woeid` to `/x/trends` |
+| `GET /radar` | Trending topics from curated sources: `category`, `region`, `hours`, `limit` |
+| `GET /x/search/autocomplete` | Suggestions for a partial query: `q` (required), `types` (comma-separated `users`, `topics`, `hashtags`, `cashtags`), `limit` (1 to 100, default 20) |
+| `GET /x/places/search` | `q` (required), `limit`. Pass a place `id` as `place` to tweet search |
+| `GET /x/hashflags` | Custom emoji X shows after hashtags: `q`, `activeOnly` (default `true`), `limit` |
+| `GET /x/links/resolve` | `urls` (required): 1 to 100 `https://t.co/` links, comma-separated. Returns each `resolvedUrl` |
+
+A trends request bills 1 credit, however many trends it returns. `woeid` wins
+when a request also names a `country` or `location`. Common WOEIDs:
+
+| Region | WOEID | Region | WOEID |
+| --- | --- | --- | --- |
+| Worldwide | 1 | France | 23424819 |
+| United States | 23424977 | Japan | 23424856 |
+| United Kingdom | 23424975 | India | 23424848 |
+| Turkey | 23424969 | Brazil | 23424768 |
+| Spain | 23424950 | Canada | 23424775 |
+| Germany | 23424829 | Mexico | 23424900 |
+
+`GET /x/trends/locations` lists every other place.
+
+Lookups, checks, insights, translations, and embeds bill 1 credit per call.
+Lists of IDs, Lists, communities, topics, Spaces, jobs, places, locations,
+hashflags, suggestions, and resolved links bill 1 credit per returned item.
+Subtitles bill 1 credit only when a caption track returns.
+[Pricing](compare-faq.md#pricing-facts) lists every rate.
+
+## Media
+
+`POST /x/media/download` with JSON `{"tweetInput": "<tweet URL or ID>"}` for
+one tweet, or `{"tweetIds": ["<id>", "..."]}` for up to 50 tweets.
+
+- One tweet returns `tweetId`, `galleryUrl`, and `cacheHit`.
+- Several tweets return `galleryUrl`, `totalTweets`, and `totalMedia`.
+- `galleryUrl` is the page where the user saves the files.
+- A tweet without media returns `400 no_media`.
+
+A download grants no reuse rights. Tell the user to confirm permission before
+using the media in their own work.
+
+## AI analysis
+
+These routes read posts and answer questions about each one with AI. Send a
+JSON body with `POST`. Each analyzed post bills 2 credits, read included.
+
+| Route | Answers |
+| --- | --- |
+| `POST /x/analysis/sentiment` | `sentiment`, `intensity`, `sarcasm` |
+| `POST /x/analysis/brand` | `relevance`, `sentiment`, `experience` for the brand in `analysis.targets` |
+| `POST /x/analysis/news` | `format`, `attribution`, `relevance` for the topic in `analysis.targets` |
+| `POST /x/analysis/market-signals` | `stance`, `content`, `conviction`, `relevance`, plus bullish & bearish counts per cashtag |
+| `POST /x/analysis/viral-score` | 8 wording traits, `viralScore` from 0 to 100 & `viralVerdict` |
+| `POST /x/analysis/classify` | 1 to 8 questions you write in `analysis.questions` |
+
+Send exactly 1 source:
+
+- `tweetIds`: up to 100 post IDs or URLs.
+- `texts`: up to 100 texts of the user's, such as drafts. Nothing is read
+  from X.
+- A search: `query`, `username`, `listId`, `quotesOf`, or `repliesTo`, alone
+  or together, with `sinceTime`, `untilTime`, `queryType`, `limit` (1 to 100,
+  default 20), and `cursor`.
+
+`analysis` is optional: `targets` (names with `aliases`), `context`,
+`questions`, or a `preset`. Question IDs and category names are lower case
+with underscores.
+
+Send each analysis once with the helpers from [Retries](#retries). A refused
+call bills nothing. Ask the user before sending it again.
+
+```python
+response = requests.post(
+    f"{BASE}/x/analysis/brand",
+    headers=HEADERS,
+    json={"username": "Sony", "limit": 50, "analysis": {"targets": [{"name": "Sony"}]}},
+    timeout=60,
+    allow_redirects=False,
+)
+page = read_body(response)
+if not 200 <= response.status_code < 300 or isinstance(page, str):
+    raise XquikError(f"{response.status_code}: {page}", response.status_code, page)
+```
+
+The response holds `results` (each post with its `answers`), `unanalyzed`
+(free, with a `reason`), `analysisSummary` (totals per question, target and
+cashtag), `has_next_page`, and `next_cursor`. Answers describe what posts say.
+They do not verify claims or give investment advice.
+
+## Private reads
+
+These need a connected X account:
+
+- `GET /x/dm/{userId}/history?account=<connected handle>`: `userId` is the
+  other person's numeric ID. Resolve it with `GET /x/users/{username}`. It
+  bills 1 credit per returned message and has no page size, so the last page
+  can go past a message target. Give the cost per message, not a hard cap.
+- `GET /x/bookmarks`, `GET /x/bookmarks/folders`, `GET /x/notifications`,
+  `GET /x/timeline`
+- `GET /x/accounts` lists connected accounts.
+
+## Pagination and errors
+
+- Follow `next_cursor` while `has_next_page` is true. Stop at the user's bound.
+  Never build or decode a cursor.
+- `409 coverage_cursor_unavailable`: wait the exact `Retry-After` seconds,
+  then retry the same cursor. The helper below does this.
+- `410 coverage_cursor_gone` or `400 invalid_coverage_cursor`: restart once
+  without a cursor and deduplicate by ID. The paging loop below catches
+  `XquikError` from the helper and restarts with the remaining budget.
+- Generated paging code keeps one result budget across the entire run. Count
+  every returned row before deduplication, including refetched rows after a
+  restart. Lower later page sizes to the remaining budget. Persist IDs
+  already appended across cron runs. An empty page can still have a cursor.
+- `429`, `5xx`, and failed connections: retry as [Retries](#retries) shows.
+
+## Retries
+
+- Retry `GET` on `429`, `409 coverage_cursor_unavailable` with `Retry-After`, `5xx`, and
+  connection failures, such as a refused or reset connection or a timeout.
+- Wait `Retry-After` when the response has it. Otherwise back off
+  exponentially from about 1 second, cap each wait at 30 seconds, and add
+  jitter. Stop after about 5 minutes and report the last error.
+- Retry the same URL and cursor, so pages are not skipped or repeated.
+- Set a request timeout, such as 30 seconds, so a stalled connection cannot
+  hang a run.
+- Do not retry other `4xx` errors. Fix the request, or handle the cursor
+  errors above.
+- Parse bodies safely. An outage can return an HTML page, even with a `2xx`
+  status, so parsing it as JSON throws. Retry that case.
+- Never retry `POST`, `PATCH`, or `DELETE` automatically. See
+  [writes](writes.md#responses-and-retries).
+
+In JavaScript, `fetch` rejects on a refused or reset connection, so catch that
+as a retryable failure. Read `await response.text()` and parse it inside
+`try`.
+
+```python
+import os
+import random
+import time
+from email.utils import parsedate_to_datetime
+
+import requests
+
+BASE = "https://xquik.com/api/v1"
+API_KEY = os.environ.get("XQUIK_API_KEY", "").strip()
+if not API_KEY or not API_KEY.isascii() or not API_KEY.isprintable():
+    raise ValueError("Set XQUIK_API_KEY to a valid API key.")
+HEADERS = {"x-api-key": API_KEY}
+NETWORK_ERRORS = (
+    requests.ConnectionError,
+    requests.Timeout,
+    requests.exceptions.ChunkedEncodingError,
+    requests.exceptions.ContentDecodingError,
+)
+
+
+class XquikError(Exception):
+    def __init__(self, message, status=None, body=None):
+        super().__init__(message)
+        self.status, self.body = status, body
+
+
+def redact(value):
+    """Replace the API key in text, lists, and dictionary keys and values."""
+    if isinstance(value, str):
+        return value.replace(API_KEY, "[redacted]")
+    if isinstance(value, dict):
+        return {redact(key): redact(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [redact(item) for item in value]
+    return value
+
+
+def retry_after(response):
+    value = response.headers.get("Retry-After", "")
+    if value.isdigit():
+        return float(value)
+    try:
+        return max(0.0, parsedate_to_datetime(value).timestamp() - time.time())
+    except (TypeError, ValueError):
+        return None
+
+
+def read_body(response):
+    """Return redacted JSON, or up to 200 characters of a redacted non-JSON body."""
+    try:
+        return redact(response.json())
+    except ValueError:
+        return redact(response.text)[:200]
+
+
+def get_json(path, params=None, budget_s=300):
+    """GET with retries for reads only. Never use it for POST, PATCH, or DELETE."""
+    deadline = time.monotonic() + budget_s
+    attempt = 0
+    while True:
+        wait, status, body = None, None, None
+        try:
+            response = requests.get(
+                f"{BASE}{path}", headers=HEADERS, params=params,
+                timeout=30, allow_redirects=False,
+            )
+        except NETWORK_ERRORS as exc:
+            problem = redact(f"connection failed: {exc}")
+        else:
+            status, body = response.status_code, read_body(response)
+            if 200 <= status < 300 and not isinstance(body, str):
+                return body
+            wait = retry_after(response)
+            problem = f"{status}: {body}"
+            busy_cursor = (
+                status == 409
+                and isinstance(body, dict)
+                and body.get("error") == "coverage_cursor_unavailable"
+                and wait is not None
+            )
+            if not (200 <= status < 300 or status >= 500 or status == 429 or busy_cursor):
+                raise XquikError(problem, status, body)
+        if wait is None:
+            wait = min(30.0, 2.0**attempt) * random.uniform(0.5, 1.0)
+        attempt += 1
+        if time.monotonic() + wait > deadline:
+            raise XquikError(
+                f"Gave up after {attempt} attempts. Last: {problem}", status, body
+            )
+        time.sleep(wait)
+```
+
+A paging loop on that helper. It restarts once on a gone or invalid cursor.
+It counts every returned tweet toward the user's number, refetched ones
+included, so the bill never passes that cap. Load `seen_ids` from earlier
+output, and make `append_row` save each row before it returns:
+
+```python
+def append_search_tweets(q, cap, seen_ids, append_row):
+    billed, cursor, restarted, cursors = 0, None, False, set()
+    while billed < cap:
+        params = {"q": q, "limit": cap - billed}
+        if cursor:
+            params["cursor"] = cursor
+        try:
+            page = get_json("/x/tweets/search", params)
+        except XquikError as err:
+            code = err.body.get("error") if isinstance(err.body, dict) else None
+            restartable = (err.status, code) in (
+                (410, "coverage_cursor_gone"),
+                (400, "invalid_coverage_cursor"),
+            )
+            if restarted or not restartable:
+                raise
+            cursor, restarted = None, True
+            cursors.clear()
+            continue
+        billed += len(page["tweets"])
+        for tweet in page["tweets"]:
+            if tweet["id"] not in seen_ids:
+                append_row(tweet)
+                seen_ids.add(tweet["id"])
+        if not page["has_next_page"] or billed >= cap:
+            break
+        cursor = page["next_cursor"]
+        if not isinstance(cursor, str) or not cursor or cursor in cursors:
+            raise XquikError("Invalid or repeated search cursor")
+        cursors.add(cursor)
+    return billed
+```