X (Twitter) Search API reference

Public posts on X matching a keyword, with a cursor. Takes a keyword, returns a cursor page, 1 credit a call.

This named API keeps X fields in X's own vocabulary. For a higher-level product page, see X (Twitter) Search API.

Endpoint

GET /v1/x/search
Authorization: Bearer sv_live_...

`POST` is also accepted with the same parameters in the request body. Send the key in the `Authorization` header, never in the query string.

Parameters

Name	Type	Required	Notes
`q`	string	yes	Search term or hashtag, up to 100 characters. Trimmed and lowercased before the lookup.
`cursor`	string	no	Cursor returned by the previous page.
`limit`	integer	no	Maximum items to return, up to 50.

Sample Request

This is a copyable request shape. Replace the sample values with the public X target or parameters your workflow uses.

curl -G 'https://api.sourcevine.io/v1/x/search' \
  -H 'Authorization: Bearer sv_live_...' \
  --data-urlencode 'q=latte art' \
  --data-urlencode 'limit=20'

Sample Response

A response this API returned, against the target above. Your values depend on the resource you ask about and when you ask.

{
  "data": {
    "items": [
      {
        "url": "https://x.com/jackinupdates/status/2092652315484254559",
        "text": "\"It’s not uncommon to find comment sections in stitches over videos of Innanen satirizing the trappings of “performative men,” trying to shove a copy of Joan Didion’s The White Album into a pair of selvedge denim with too-small pockets or attempting to lure NYC art baddies into a date with an iced matcha latte and a neo-feminist screenplay.\" (via Rolling Stone)",
        "likes": 21,
        "views": 831,
        "cached": false,
        "quotes": 0,
        "replies": 0,
        "tweetId": "2092652315484254559",
        "retweets": 2,
        "bookmarks": 4,
        "fetchedAt": "2026-09-02T07:13:49Z",
        "authorLink": "https://x.com/jackinupdates",
        "publishedAt": "Wed Aug 26 16:36:06 +0000 2026",
        "authorHandle": "jackinupdates",
        "cacheAgeSeconds": null,
        "sourceTimestamp": null
      },
      {
        "url": "https://x.com/Sarahhuniverse/status/2094892163041792001",
        "text": "Amazing Latte Art 😍\n\n© latteartseruveni https://t.co/a4LnFM8YW7",
        "likes": 25,
        "views": 5086,
        "cached": false,
        "quotes": 0,
        "replies": 0,
        "tweetId": "2094892163041792001",
        "retweets": 4,
        "bookmarks": 3,
        "fetchedAt": "2026-09-02T07:13:49Z",
        "authorLink": "https://x.com/Sarahhuniverse",
        "publishedAt": "Tue Sep 01 20:56:27 +0000 2026",
        "authorHandle": "Sarahhuniverse",
        "cacheAgeSeconds": null,
        "sourceTimestamp": null
      },
      {
        "url": "https://x.com/Ciri_ai/status/2094706780114952303",
        "text": "Made with seedance 2.5\n\nPrompt: Create a 30-second, 1080p ultra-realistic personal home-video showing a young Korean woman attempting to film an \"aesthetic\" café vlog for her social media and everything comically not going to plan. No reference image.\nMAIN SUBJECT\nYoung Korean woman in her early 20s, trendy and put-together look, dewy makeup, confident expression that keeps cracking into laughter.\nStraight black hair with curtain bangs, small gold hoop earrings, soft pink lip…",
        "likes": 196,
        "views": 7979,
        "cached": false,
        "quotes": 0,
        "replies": 23,
        "tweetId": "2094706780114952303",
        "retweets": 4,
        "bookmarks": 26,
        "fetchedAt": "2026-09-02T07:13:49Z",
        "authorLink": "https://x.com/Ciri_ai",
        "publishedAt": "Tue Sep 01 08:39:48 +0000 2026",
        "authorHandle": "Ciri_ai",
        "cacheAgeSeconds": null,
        "sourceTimestamp": null
      }
    ],
    "cached": false,
    "fetchedAt": null,
    "nextCursor": null,
    "cacheAgeSeconds": null
  },
  "success": true,
  "available": true
}

Fields

Field	Type	Notes
`items`	array	A page of public X posts or videos.
`nextCursor`	string \| null	Pass as cursor to request the next page.
`items[].views`	integer \| null	Present only where the platform reports it.
`items[].likes`	integer \| null	Per-item public like count.
`items[].cached`	boolean	Matches the page provenance on cached reads.
`fetchedAt`	ISO datetime	When Sourcevine read the public page.
`sourceTimestamp`	ISO datetime \| null	The platform timestamp when it is available.
`cached`	boolean	True when this answer repeats an identical request made moments earlier.
`cacheAgeSeconds`	integer	Seconds since the reading was taken.

Availability States

Status	Charged	Client behavior
`available`	yes for live reads	Use data.
`not_found`	yes	Store the state and stop polling.
`private`	yes	Store the state and stop polling.
`unsupported`	no	Fix the URL or call the matching API.
`upstream_unavailable`	no	Retry later with backoff.

Unavailable resources return `success: true`, `available: false`, `availability`, and `data: null`. API or authentication failures return `success: false` with an `error` object.

Billing

A call costs 1 credit. A deleted, private or empty resource is charged like any lookup and says so. An unsupported URL or a read we could not complete is not charged. The `X-Credits-Charged` response header is the source of truth for what happened on that request.

Successful responses include `fetchedAt`, the time we read the platform.

What This API Does Not Return

No contact or bio fields: Bios, email addresses, phone numbers, postal addresses and messenger handles are outside the response contract.
No private data: Private accounts, restricted content and unavailable resources return typed availability instead of guessed data.
No comments or downloads: List APIs return recent public post metadata and metrics. They do not return comment bodies, media files or hidden analytics.

Last updated 1 September 2026