Skip to main content
GET https://xquik.com/api/v1/x/tweets/search
Repost records include retweetedAt, the repost event’s UTC ISO 8601 timestamp. It is null when that timestamp is unavailable. The API omits it for original posts. The nested original post keeps its own creation date. This field does not report every account that reposted a post. Request per-account timestamps with Get retweeters.
Requested counts are upper bounds for paid calls. When credits can’t cover the full page or ID list, Xquik returns fewer results. While has_next_page is true, send next_cursor as cursor. Keep the same query, filters, queryType & limit. With 0 affordable results, it returns 402 insufficient_credits.
Search Tweets accepts keywords, hashtags, operators, dates, authors, media, and engagement filters. For exact lookup, send a Tweet ID or X status URL in q. Send it with no time params. To search one user’s tweets as a plain timeline, call Search user tweets (GET /x/users/{id}/tweets). Date params limit results to that window, as in q=from:username&sinceTime=2026-05-01&untilTime=2026-05-02. Cursor requests return an empty final page for exact IDs.
1 credit per tweet returned · All plans from $0.00012/credit
Omit mode to get the fullest results. The response shape stays the same. Pass next_cursor back unchanged as cursor. Keep the same endpoint, target, query, and filters.
Existing unprefixed cursors keep their legacy behavior. after, limit, and pageSize aliases also keep working. Billing still counts only returned rows. Use mode=standard only to keep the legacy pagination. A page can be empty or underfilled. Continue while has_next_page is true. Stop only after the response reports has_next_page=false. First-page requests do not support Idempotency-Key retries. Repeating a cursorless request starts a separate extraction. Results returned by that extraction incur their normal charges. Save each response before requesting its next page. A cursor sent again within 10 minutes returns the same page at no charge. After 10 minutes, you cannot replay earlier or terminal responses. If automatic coverage is busy, an initial request returns a standard data page. Live coverage cursors remain atomic. A cursor sent again while its page loads returns that page at no charge. Other repeats return 409 coverage_cursor_unavailable with exact Retry-After seconds. Wait, then send the same cursor again. Repeated busy responses never authorize restarting with another cursor. Expired, superseded, or identity-mismatched cursors return 410 coverage_cursor_gone. So does a cursor sent again after 10 minutes. The response omits Retry-After. Restart without a cursor. Keep received results. Deduplicate restarted results by id. Malformed cursors return 400 invalid_coverage_cursor. Restart without them. A search with no results ends with has_next_page=false.

Direct API handoff

Use GET /x/tweets/search for live JSON. Store IDs and next_cursor to resume. Use tweet_search_extractor for estimates, saved pages, or downloadable CSV, JSON, and XLSX files. limit bounds unique matching tweets after filtering. Keep q, filters, queryType, and limit unchanged when resuming with cursor=next_cursor. Continue while has_next_page is true. Deduplicate IDs and reject repeated cursors. Explicit mode=coverage returns retained rows when its request window expires. Check diagnostic.deadlineReached and diagnostic.complete. Partial coverage does not mean the source ran out of tweets. For account date windows, sinceTime and untilTime limit results to that window. Inline since_time: and until_time: intersect. The start is inclusive. The end is exclusive. Days are UTC. q=from:username&sinceTime=2026-05-01&untilTime=2026-05-02 behaves like from:username since:2026-05-01 until:2026-05-02. Use queryType=Latest for backfills or keywords for ranked search. Bounds apply to every returned page. Coverage continues past rejected rows. -filter:nativeretweets drops button reposts but keeps quotes & manual RT text. include:nativeretweets adds button reposts to author searches. -filter:retweets also drops manual RT text. Xquik keeps the operator you send. Account searches return all of the account’s posts & reposts in the window. Continue when the response includes next_cursor. mode=standard keeps the legacy behavior for old integrations. A search that needs a protected author returns 403 with x_account_protected and no charge. Choose a public account. Searches across several authors are unaffected.

Advanced Twitter search patterns

Tweet rows

Store tweets[] as the matching tweet rows for app ingestion, analyst export, or retrieval.

Tweet keys

Store tweets[].id as the stable tweet key. Use it for deduplication, CRM notes, queues, and follow-up lookups.

Search context

Store tweets[].text and tweets[].createdAt for search hit context and time ordering.

Author joins

Store tweets[].author.id, tweets[].author.username, tweets[].author.name, tweets[].author.followers, tweets[].author.verified, and tweets[].author.profilePicture for author joins and enrichment.

Scoring fields

Store engagement counts for scoring, routing, and prioritization.

Relationship context

Store tweets[].media, quoted_tweet & retweeted_tweet for media & relationship context.

Next page

Store has_next_page and next_cursor as the cursor handoff. For bounded limit batches, keep the same query, filters, queryType, and limit when resuming.

File exports

Use tweet_search_extractor when the output must be saved CSV, JSON, or XLSX.
Tweet search costs 1 credit per tweet returned. With topic, each kept post costs 2 credits. A dropped post costs nothing. Retry 429 with the Retry-After header. Retry 502 after a short backoff. Change the query after 424 search_unavailable.

Keep only posts about a topic

A word like rust or jaguar matches many meanings. Send topic to name the one you want. AI-powered analysis asks Is this post about <topic>? of each post the search reads. Posts scoring 0.5 or more come back, each with its topicScore. The check reads the post text & photos X doesn’t mark sensitive.
  • Each kept post costs 2 credits, the AI analysis price, instead of 1. A post the filter drops costs nothing.
  • limit counts checked posts. Only kept posts come back.
  • unchecked lists posts the check couldn’t answer. They cost nothing & stay out.
  • Follow next_cursor with the same topic to check the next posts.

Matched text ranges

Each row says where its text matches the search, in textHighlights. Use the ranges to bold the matched words or cut a snippet around them.
  • startIndex is the first code point of a match. endIndex is the first one after it.
  • Offsets count code points of the row’s text, as displayTextRange does.
  • JavaScript counts some characters, such as most emoji, as 2 units. Split the text by code point first.
  • The list is empty when X marks nothing. One case is a from: search without words.
  • X marks matches only in a post’s first 280 characters. Later matches in a long post get no range.

Query parameters

Structured filters

Structured filters are part of the public Search Tweets API. Use X search operators. Keep the same filters on every cursor request.See tweet filters for every filter. Common ones are fromUser, language, sinceDate, mediaType, minLikes, and hashtags.

Search-only operators

These query parameters apply only to GET /x/tweets/search. That is because they map to search operators before the request runs. Use advancedQuery only when you have trusted raw X search operator syntax to append.

Keep posts by topic or photo

Send 1 of these to keep only the posts you want. AI-powered analysis checks each post the page reads. Posts scoring 0.5 or more come back, each with its score. Each kept post costs 2 credits instead of 1. A dropped post costs nothing. The page size counts checked posts. Posts the check can’t answer cost nothing & stay out. They need an Xquik API key, since each kept post bills Xquik credits. RapidAPI & pay-per-request calls with them get 400 invalid_input.

Choose fields

Headers

Response

200 OK

400 Missing query

The q query parameter is empty or missing.

401 Unauthenticated

Anonymous requests get WWW-Authenticate: Bearer and a guest wallet checkout action. This is not a Payment challenge. Missing or invalid API key. Check the x-api-key header value.

402 Payment required

Account keys get account options. Guest keys get guest top-up only. No checkout starts automatically. Confirm any payment action.

404 Missing user or tweet

user_not_found means a required user lookup failed. Check the username. tweet_not_found means an exact tweet lookup failed. Check the tweet ID or URL. Neither means a search completed with no matching tweets.

502 X API unavailable

The read service returned an error. Retry after a short delay.

429 Rate limit exceeded

You exceeded your tier rate limit. Wait for the Retry-After header before retrying.

424 Search unavailable

{ "error": "search_unavailable" } X fails this query on every read, so a retry fails too. Follow its message to fix the search. The normalized v1 contract also returns 424 x_api_unavailable.
Next steps. Tweet Search Export Workflow when you need saved CSV, JSON, or XLSX files. Get Tweet to fetch full details for a specific tweet. Get User to look up an author profile.

Response examples

  • 400 { "error": "missing_query", "message": "Search query required. Use q." }
  • 401 { "error": "unauthenticated", "message": "Authentication required." }
  • 402 { "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." }
  • 403 { "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." }
  • 404 { "error": "not_found", "message": "Resource not found." }
  • 409 { "error": "coverage_cursor_unavailable", "message": "Cursor busy. Retry after the indicated delay." }
  • 410 { "error": "coverage_cursor_gone", "message": "Cursor finished, expired, or superseded. Restart pagination without cursor." }
  • 424 { "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }
  • 429 { "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }
  • 502 { "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }
  • 503 { "error": "x_api_unavailable", "message": "Maximum coverage is busy. Retry shortly." }