API reference · Twitter

twitter/bulk/tweet-search

Integrate this model through SandBase's unified API, with production-ready schemas and examples.

APIAsyncOpen model

Production endpoint

Send your first request

OpenAI-compatible endpoint with unified authentication and usage tracking.

POSThttps://api.sandbase.ai/v1/run

Model IDtwitter/bulk/tweet-search

Input Schema

26 parameters · 0 required · 26 optional

Parameter	Type	Required	Description
`end`	string	Optional	Returns tweets sent before the given date.
`sort`	string	Optional	Sorts search results. If you are getting low results, try Top instead of Latest. Latest + Top runs both simultaneously to maximize results but may return some duplicate tweets. · Options: Top, Latest, Latest + Top TopLatestLatest + Top
`start`	string	Optional	Returns tweets sent after the given date.
`author`	string	Optional	Returns tweets sent by the given user. It should be a Twitter (X) Handle.
`geocode`	string	Optional	Returns tweets sent by users located within a given radius of the given latitude/longitude.
`maxItems`	integer	Optional	Maximum number of items that you want as output. · Min: -9007199254740991 · Max: 9007199254740991
`inReplyTo`	string	Optional	Returns tweets that are replies to the given user. It should be a Twitter (X) Handle.
`onlyImage`	boolean	Optional	If selected, only returns tweets that contain images.
`onlyQuote`	boolean	Optional	If selected, only returns tweets that are quotes.
`onlyVideo`	boolean	Optional	If selected, only returns tweets that contain videos.
`startUrls`	array	Optional	Twitter (X) URLs. Paste the URLs and get the results immediately. Tweet, Profile, Search or List URLs are supported.
`mentioning`	string	Optional	Returns tweets mentioning the given user. It should be a Twitter (X) Handle.
`searchTerms`	array	Optional	Search terms you want to search from Twitter (X). You can refer to https://github.com/igorbrigadir/twitter-advanced-search.
`withinRadius`	string	Optional	Returns tweets sent within the given radius of the given location.
`geotaggedNear`	string	Optional	Returns tweets sent near the given location.
`placeObjectId`	string	Optional	Returns tweets tagged with the given place.
`tweetLanguage`	string	Optional	Restricts tweets to the given language, given by an ISO 639-1 code. · Options: ab, aa, af, ak, sq, am, ar, an, hy, as, av, ae, ay, az, bm, ba, eu, be, bn, bi, bs, br, bg, my, ca, ch, ce, ny, zh, cu, cv, kw, co, cr, hr, cs, da, dv, nl, dz, en, eo, et, ee, fo, fj, fi, fr, fy, ff, gd, gl, lg, ka, de, el, kl, gn, gu, ht, ha, he, hz, hi, ho, hu, is, io, ig, id, ia, ie, iu, ik, ga, it, ja, jv, kn, kr, ks, kk, km, ki, rw, ky, kv, kg, ko, kj, ku, lo, la, lv, li, ln, lt, lu, lb, mk, mg, ms, ml, mt, gv, mi, mr, mh, mn, na, nv, nd, nr, ng, ne, no, nb, nn, ii, oc, oj, or, om, os, pi, ps, fa, pl, pt, pa, qu, ro, rm, rn, ru, se, sm, sg, sa, sc, sr, sn, sd, si, sk, sl, so, st, es, su, sw, ss, sv, tl, ty, tg, ta, tt, te, th, bo, ti, to, ts, tn, tr, tk, tw, ug, uk, ur, uz, ve, vi, vo, wa, cy, wo, xh, yi, yo, za, zu abaaafaksqamaranhyasavaeayazbmbaeubebnbibsbrbgmycachcenyzhcucvkwcocrhrcsdadvnldzeneoeteefofjfifrfyffgdgllgkadeelklgnguhthahehzhihohuisioigidiaieiuikgaitjajvknkrkskkkmkirwkykvkgkokjkulolalvlilnltlulbmkmgmsmlmtgvmimrmhmnnanvndnrngnenonbnniiocojoromospipsfaplptpaqurormrnrusesmsgsascsrsnsdsiskslsostessuswsssvtltytgtatttethbotitotstntrtktwugukuruzvevivowacywoxhyiyozazu
`minimumReplies`	integer	Optional	Returns tweets with at least the given number of replies. · Min: -9007199254740991 · Max: 9007199254740991
`twitterHandles`	array	Optional	Twitter handles that you want to search on Twitter (X)
`conversationIds`	array	Optional	Conversation IDs that you want to search on Twitter (X)
`minimumRetweets`	integer	Optional	Returns tweets with at least the given number of retweets. · Min: -9007199254740991 · Max: 9007199254740991
`onlyTwitterBlue`	boolean	Optional	If selected, only returns tweets by users who are Twitter Blue subscribers.
`minimumFavorites`	integer	Optional	Returns tweets with at least the given number of favorites. · Min: -9007199254740991 · Max: 9007199254740991
`customMapFunction`	string	Optional	Function that takes each of the objects as argument and returns data that will be mapped by the function itself. This function is not intended for filtering, please don't use it for filtering purposes or you will get banned automatically.
`onlyVerifiedUsers`	boolean	Optional	If selected, only returns tweets by users who are verified.
`includeSearchTerms`	boolean	Optional	If selected, a field will be added to each tweets about the search term that was used to find it.

Output Schema

Field	Type	Description
`id`	string	Unique identifier for the generation task
`status`	string	Task status: pending, running, completed, failed, timeout
`model`	string	Model used for the generation
`outputs`	array	Array of output items
`outputs[].url`	string	URL of the generated artifact
`outputs[].content_type`	string	MIME type (e.g. image/png, video/mp4)
`error`	object \| null	Error details if failed, null on success
`error.type`	string	Machine-readable error type code
`error.message`	string	Human-readable error description

Async Workflow

This model uses asynchronous execution. Submit a request and poll for the result.

Submit — POST to /v1/run, receive an id
Poll — GET /v1/run/{id} until status is completed, failed, or timeout
Retrieve — Read outputs from the completed response

Code Examples

Ready-to-run snippets

# Step 1: Submit
curl -X POST https://api.sandbase.ai/v1/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "model": "twitter/bulk/tweet-search",
  "prompt": "a beautiful sunset over mountains"
}'

# Step 2: Poll result (replace <id>)
curl https://api.sandbase.ai/v1/run/<id> \
  -H "Authorization: Bearer YOUR_API_KEY"

← Back to Tweet Search