Skip to content

Commit 148dd1b

Browse files
Burak Bayırkriptoburak
Burak Bayır
and
kriptoburak
authored
Document automatic maximum coverage pagination (#397)
* docs: explain automatic maximum coverage * chore(docs): patch toolchain advisories * docs: explain Tweet search pressure recovery --------- Co-authored-by: kriptoburak <kriptoburak@users.noreply.github.com>
1 parent cbd873e commit 148dd1b

22 files changed

Lines changed: 2065 additions & 777 deletions

‎api-reference/extractions/twitter-extraction-results.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,15 @@ import LlmsDirective from "/snippets/llms-directive.mdx";
2525
```
2626
</Tab>
2727

28+
<Tab title="400" id="response-extractions-twitter-extraction-results-400">
29+
```json
30+
{
31+
"error": "invalid_input",
32+
"message": "Invalid input. Check the request body."
33+
}
34+
```
35+
</Tab>
36+
2837
<Tab title="401" id="response-extractions-twitter-extraction-results-401">
2938
```json
3039
{

‎api-reference/x/batch-tweets.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@ import TweetReadApiLinks from "/snippets/x-tweet-read-api-links.mdx";
2424
"retweetCount": 5
2525
}
2626
],
27-
"has_next_page": true,
28-
"next_cursor": "DAACCgACGRElMJcAAA"
27+
"has_next_page": false,
28+
"next_cursor": ""
2929
}
3030
```
3131
</Tab>

‎api-reference/x/followers.mdx‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ keywords: ["Twitter followers", "get Twitter followers", "Twitter follower track
88

99
import LlmsDirective from "/snippets/llms-directive.mdx";
1010
import AudienceCommunityApiLinks from "/snippets/x-audience-community-api-links.mdx";
11+
import AutomaticCoveragePagination from "/snippets/automatic-coverage-pagination.mdx";
1112

1213
{/* GENERATED RESPONSE EXAMPLES START */}
1314
<Panel>
@@ -64,6 +65,15 @@ import AudienceCommunityApiLinks from "/snippets/x-audience-community-api-links.
6465
```
6566
</Tab>
6667

68+
<Tab title="409" id="response-x-followers-409">
69+
```json
70+
{
71+
"error": "coverage_cursor_unavailable",
72+
"message": "Cursor expired or busy. Retry once, then restart pagination."
73+
}
74+
```
75+
</Tab>
76+
6777
<Tab title="424" id="response-x-followers-424">
6878
```json
6979
{
@@ -91,6 +101,15 @@ import AudienceCommunityApiLinks from "/snippets/x-audience-community-api-links.
91101
}
92102
```
93103
</Tab>
104+
105+
<Tab title="503" id="response-x-followers-503">
106+
```json
107+
{
108+
"error": "x_api_unavailable",
109+
"message": "Maximum coverage is busy. Retry shortly."
110+
}
111+
```
112+
</Tab>
94113
</Tabs>
95114
</Panel>
96115
{/* GENERATED RESPONSE EXAMPLES END */}
@@ -105,6 +124,8 @@ import AudienceCommunityApiLinks from "/snippets/x-audience-community-api-links.
105124
Get followers returns follower profiles for one X account by username or numeric user ID. It is also useful as a Follower Export API, X followers API, or Twitter followers API. The canonical endpoint remains `GET /api/v1/x/users/{id}/followers`.
106125
</Info>
107126

127+
<AutomaticCoveragePagination />
128+
108129
<CodeGroup>
109130
```bash cURL
110131
# Username follower page
@@ -342,7 +363,14 @@ partial.
342363
## Query parameters
343364
344365
<ParamField query="cursor" type="string">
345-
Opaque pagination cursor from `next_cursor` in the previous response. Omit for the first page.
366+
Pass `next_cursor` back unchanged. New Xquik cursors resume automatic
367+
coverage. Existing unprefixed cursors keep legacy behavior.
368+
</ParamField>
369+
370+
<ParamField query="mode" type="string">
371+
Optional compatibility override. Omit it for automatic maximum coverage.
372+
Use `standard` for legacy single-view pagination. Use `coverage` for a
373+
one-shot diagnostic response without cursor pagination.
346374
</ParamField>
347375
348376
<ParamField query="after" type="string">
@@ -354,7 +382,8 @@ partial.
354382
</ParamField>
355383
356384
<ParamField query="limit" type="number">
357-
Legacy page size alias. Use `pageSize`; when both are present, `pageSize` wins.
385+
With `mode=coverage`, set a one-shot cap from `1` through `10000`.
386+
Otherwise, this is a legacy page size alias. `pageSize` wins.
358387
</ParamField>
359388
360389
## Headers

‎api-reference/x/following.mdx‎

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ keywords: ["Twitter following", "Twitter following API", "Twitter following trac
88

99
import LlmsDirective from "/snippets/llms-directive.mdx";
1010
import AudienceCommunityApiLinks from "/snippets/x-audience-community-api-links.mdx";
11+
import AutomaticCoveragePagination from "/snippets/automatic-coverage-pagination.mdx";
1112

1213
{/* GENERATED RESPONSE EXAMPLES START */}
1314
<Panel>
@@ -64,6 +65,15 @@ import AudienceCommunityApiLinks from "/snippets/x-audience-community-api-links.
6465
```
6566
</Tab>
6667

68+
<Tab title="409" id="response-x-following-409">
69+
```json
70+
{
71+
"error": "coverage_cursor_unavailable",
72+
"message": "Cursor expired or busy. Retry once, then restart pagination."
73+
}
74+
```
75+
</Tab>
76+
6777
<Tab title="424" id="response-x-following-424">
6878
```json
6979
{
@@ -91,6 +101,15 @@ import AudienceCommunityApiLinks from "/snippets/x-audience-community-api-links.
91101
}
92102
```
93103
</Tab>
104+
105+
<Tab title="503" id="response-x-following-503">
106+
```json
107+
{
108+
"error": "x_api_unavailable",
109+
"message": "Maximum coverage is busy. Retry shortly."
110+
}
111+
```
112+
</Tab>
94113
</Tabs>
95114
</Panel>
96115
{/* GENERATED RESPONSE EXAMPLES END */}
@@ -112,6 +131,8 @@ Use this route for accounts the selected user follows. Use followers for inbound
112131
`GET /api/v1/x/users/{id}/following`.
113132
</Info>
114133

134+
<AutomaticCoveragePagination />
135+
115136
<CodeGroup>
116137
```bash Username
117138
curl "https://xquik.com/api/v1/x/users/username/following?pageSize=100" \
@@ -279,8 +300,14 @@ partial snapshot.
279300
## Query parameters
280301
281302
<ParamField query="cursor" type="string">
282-
Pagination cursor from `next_cursor` in a previous response. Omit for the
283-
first page. Pass a cursor only when `has_next_page` is true.
303+
Pass `next_cursor` back unchanged. New Xquik cursors resume automatic
304+
coverage. Existing unprefixed cursors keep legacy behavior.
305+
</ParamField>
306+
307+
<ParamField query="mode" type="string">
308+
Optional compatibility override. Omit it for automatic maximum coverage.
309+
Use `standard` for legacy single-view pagination. Use `coverage` for a
310+
one-shot diagnostic response without cursor pagination.
284311
</ParamField>
285312
286313
<ParamField query="after" type="string">
@@ -293,7 +320,8 @@ partial snapshot.
293320
</ParamField>
294321
295322
<ParamField query="limit" type="number">
296-
Legacy page size alias. Use `pageSize`; when both are present, `pageSize` wins.
323+
With `mode=coverage`, set a one-shot cap from `1` through `10000`.
324+
Otherwise, this is a legacy page size alias. `pageSize` wins.
297325
</ParamField>
298326
299327
## Which following endpoint?

‎api-reference/x/search-tweets.mdx‎

Lines changed: 40 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ keywords: ["Twitter search", "advanced Twitter search", "Twitter search API", "s
77
---
88

99
import LlmsDirective from "/snippets/llms-directive.mdx";
10+
import AutomaticCoveragePagination from "/snippets/automatic-coverage-pagination.mdx";
1011
import TweetResultFilterParams from "/snippets/tweet-result-filter-params.mdx";
1112
import TweetSearchOnlyFilterParams from "/snippets/tweet-search-only-filter-params.mdx";
1213

@@ -57,6 +58,15 @@ import TweetSearchOnlyFilterParams from "/snippets/tweet-search-only-filter-para
5758
```
5859
</Tab>
5960

61+
<Tab title="409" id="response-x-search-tweets-409">
62+
```json
63+
{
64+
"error": "coverage_cursor_unavailable",
65+
"message": "Cursor expired or busy. Retry once, then restart pagination."
66+
}
67+
```
68+
</Tab>
69+
6070
<Tab title="424" id="response-x-search-tweets-424">
6171
```json
6272
{
@@ -84,6 +94,15 @@ import TweetSearchOnlyFilterParams from "/snippets/tweet-search-only-filter-para
8494
}
8595
```
8696
</Tab>
97+
98+
<Tab title="503" id="response-x-search-tweets-503">
99+
```json
100+
{
101+
"error": "x_api_unavailable",
102+
"message": "Maximum coverage is busy. Retry shortly."
103+
}
104+
```
105+
</Tab>
87106
</Tabs>
88107
</Panel>
89108
{/* GENERATED RESPONSE EXAMPLES END */}
@@ -113,6 +132,14 @@ import TweetSearchOnlyFilterParams from "/snippets/tweet-search-only-filter-para
113132
**1 credit per tweet returned** · [All plans](https://xquik.com/#pricing) from $0.00012/credit
114133
</Callout>
115134

135+
<AutomaticCoveragePagination />
136+
137+
<Info>
138+
Fresh searches return available automatic rows when some views fail. If
139+
automatic coverage cannot start, Xquik uses standard pagination. Coverage
140+
cursors never switch sources mid-sequence.
141+
</Info>
142+
116143
<CodeGroup>
117144
```bash cURL
118145
curl -G https://xquik.com/api/v1/x/tweets/search \
@@ -230,9 +257,9 @@ For account date windows, `sinceTime` and `untilTime` append `since:` and
230257
`from:username since:2026-05-01 until:2026-05-02`. Use `queryType=Latest` for
231258
chronological backfills. Add keywords for ranked search.
232259
233-
For bounded `limit`, bare `q=from:username` with no time params is a user
234-
timeline pull and returns one page with `has_next_page: false`. Add a search
235-
term or use `fromUser` with a keyword for search pagination.
260+
Bare `q=from:username` uses automatic timeline and search coverage. Continue
261+
when the response includes `next_cursor`. Use `mode=standard` only when an old
262+
integration requires the legacy single-page timeline behavior.
236263
237264
For exact lookups, a plain Tweet ID or X status URL in `q` returns that tweet
238265
when available. Send no cursor on the first lookup; cursor requests return an
@@ -296,8 +323,15 @@ Tweet search costs 1 credit per tweet returned. Low credit balances can return f
296323
Sort order for search results. `Top` returns most relevant tweets, `Latest` returns most recent. Defaults to `Latest`.
297324
</ParamField>
298325
326+
<ParamField query="mode" type="string">
327+
Optional compatibility override. Omit it for automatic maximum coverage.
328+
Use `standard` for legacy single-view pagination. Use `coverage` for a
329+
one-shot diagnostic response without cursor pagination.
330+
</ParamField>
331+
299332
<ParamField query="cursor" type="string">
300-
Pagination cursor. Pass the `next_cursor` value from the previous response to fetch the next page.
333+
Pass `next_cursor` back unchanged. New Xquik cursors resume automatic
334+
coverage. Existing unprefixed cursors keep legacy behavior.
301335
</ParamField>
302336
303337
<ParamField query="sinceTime" type="string">
@@ -309,9 +343,8 @@ Tweet search costs 1 credit per tweet returned. Low credit balances can return f
309343
</ParamField>
310344
311345
<ParamField query="limit" type="integer">
312-
Maximum number of tweets to collect in one bounded request (1-200). If the
313-
response includes `has_next_page: true`, keep the same `limit` when continuing
314-
with `cursor`.
346+
Maximum Tweets requested per automatic page. Use `1` through `10000`.
347+
A page can return fewer. Keep the same limit when continuing with `cursor`.
315348
</ParamField>
316349
317350
### Structured filters

‎api-reference/x/tweet-replies.mdx‎

Lines changed: 28 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ keywords: ["Twitter API get replies", "Twitter API get replies to a tweet", "get
77
---
88

99
import LlmsDirective from "/snippets/llms-directive.mdx";
10+
import AutomaticCoveragePagination from "/snippets/automatic-coverage-pagination.mdx";
1011
import TweetReadApiLinks from "/snippets/x-tweet-read-api-links.mdx";
1112
import TweetResultFilterParams from "/snippets/tweet-result-filter-params.mdx";
1213

@@ -74,6 +75,15 @@ import TweetResultFilterParams from "/snippets/tweet-result-filter-params.mdx";
7475
```
7576
</Tab>
7677

78+
<Tab title="409" id="response-x-tweet-replies-409">
79+
```json
80+
{
81+
"error": "coverage_cursor_unavailable",
82+
"message": "Cursor expired or busy. Retry once, then restart pagination."
83+
}
84+
```
85+
</Tab>
86+
7787
<Tab title="424" id="response-x-tweet-replies-424">
7888
```json
7989
{
@@ -106,7 +116,7 @@ import TweetResultFilterParams from "/snippets/tweet-result-filter-params.mdx";
106116
```json
107117
{
108118
"error": "x_api_unavailable",
109-
"message": "Complete reply extraction is busy. Retry shortly."
119+
"message": "Maximum coverage is busy. Retry shortly."
110120
}
111121
```
112122
</Tab>
@@ -124,6 +134,8 @@ import TweetResultFilterParams from "/snippets/tweet-result-filter-params.mdx";
124134
**1 credit per tweet returned** · [All plans](https://xquik.com/#pricing) from $0.00012/credit · Supports [guest paid reads](/guides/guest-wallets)
125135
</Callout>
126136

137+
<AutomaticCoveragePagination />
138+
127139
<Info>
128140
Get tweet replies returns reply tweets for one X post by numeric tweet ID. Use
129141
it for conversation analysis, support queues, moderation review, giveaway
@@ -203,7 +215,7 @@ before requesting another cursor. Use `reply_extractor` for fixed
203215
--data-urlencode "untilTime=1777478400" \
204216
-H "x-api-key: xq_your_api_key_here" | jq
205217

206-
# Request maximum reply coverage
218+
# Request advanced nested-reply diagnostics
207219
curl -G "https://xquik.com/api/v1/x/tweets/1893456789012345678/replies" \
208220
--data-urlencode "mode=complete" \
209221
--data-urlencode "limit=25000" \
@@ -369,24 +381,25 @@ each conversation branch.
369381
370382
## Query parameters
371383
372-
<ParamField query="mode" type="string" default="standard">
373-
Use `standard` for cursor pages and filters. Use `complete` for maximum
374-
direct-reply coverage. Complete mode accepts only `limit`.
384+
<ParamField query="mode" type="string">
385+
Optional advanced override. Omit it for automatic maximum direct-reply
386+
coverage. Use `standard` for legacy pagination. Use `complete` for nested
387+
replies and detailed diagnostics. Complete mode accepts only `limit`.
375388
</ParamField>
376389
377-
<ParamField query="limit" type="number" default="25000">
378-
Maximum combined direct and nested replies in complete mode. Use `1` through
379-
`25000`. In standard mode, this deprecated alias accepts `1` through `100`.
390+
<ParamField query="limit" type="number">
391+
Maximum combined replies in complete mode. Use `1` through `25000`.
392+
Complete mode defaults to `25000`. Otherwise, use `1` through `100`.
380393
</ParamField>
381394
382395
<ParamField query="pageSize" type="number" default="20">
383-
Maximum replies requested in standard mode. Use `1` through `100`. Omit this
384-
field in complete mode. Deprecated `limit` and `count` aliases remain.
396+
Maximum replies per automatic or standard page. Use `1` through `100`. Omit
397+
this field in complete mode. Deprecated `limit` and `count` aliases remain.
385398
</ParamField>
386399
387400
<ParamField query="cursor" type="string">
388-
Opaque cursor for standard mode. Omit it initially. Then pass the returned
389-
`next_cursor` while `has_next_page` remains `true`.
401+
Pass `next_cursor` back unchanged. New Xquik cursors resume automatic
402+
coverage. Existing unprefixed cursors keep legacy behavior.
390403
</ParamField>
391404
392405
<ParamField query="sinceTime" type="string">
@@ -401,9 +414,9 @@ each conversation branch.
401414
402415
### Tweet result filters
403416
404-
These optional filters apply only in standard mode. They keep the same parent
405-
tweet and filter rows after retrieval. Selective filters can return fewer rows.
406-
Remove every filter before requesting complete mode.
417+
These filters apply to automatic and standard pagination. They keep the same
418+
parent tweet and filter rows after retrieval. Selective filters can return
419+
fewer rows. Remove every filter before requesting complete mode.
407420
408421
<TweetResultFilterParams />
409422

0 commit comments

Comments
 (0)