X post search API reference

GET /v1/twitter/search/posts

Public posts found through a web search engine (DuckDuckGo, restricted to x.com), then read like tweet through X's public post widget, so views, retweet and bookmark counts are missing. This is engine-indexed discovery, not X's own search (which needs a login): coverage is incomplete, recent posts can be missing and the order is the engine's. Deleted, protected and unreachable posts are left out. Cursor pages 1 to 11.

Cost: 1 credit
Cache: Results are kept up to 30 days; send max_age_days to reuse them for free.
Timeout: A request still running after about 25 seconds answers 202 with a job to poll (Batch and jobs).

Parameters#

Name	Type	Required	Description
`query`	string	yes	Keyword or phrase to look for in public X posts. Also accepted as `keyword`, `q`.

Every request also accepts:

cursor: the cursor from the previous page (Pagination).
trim: true for a smaller response without null fields and extra.
raw: true to also get the platform's original object as raw.
max_age_days: accept a cached result up to this many days old, for 0 credits (Caching).

Example request#

Set your key in the environment first (see Authentication).

1curl -G "https://api.socialscrape.dev/v1/twitter/search/posts" \2  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \3  --data-urlencode "query=ai agents"

1import os2import requests34params = {5    "query": "ai agents",6}7res = requests.get(8    "https://api.socialscrape.dev/v1/twitter/search/posts",9    headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},10    params=params,11)12body = res.json()1314if body["ok"]:15    print(body["data"])16else:17    print(body["error"]["code"], body["error"]["message"])

1const url = new URL("https://api.socialscrape.dev/v1/twitter/search/posts");2url.search = new URLSearchParams({3  "query": "ai agents"4}).toString();5const res = await fetch(url, {6  headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },7});8const body = await res.json();910if (body.ok) {11  console.log(body.data);12} else {13  console.error(body.error.code, body.error.message);14}

1{2  "nodes": [3    {4      "name": "SocialScrape X post search",5      "type": "n8n-nodes-base.httpRequest",6      "typeVersion": 4.2,7      "position": [8        0,9        010      ],11      "parameters": {12        "method": "GET",13        "url": "https://api.socialscrape.dev/v1/twitter/search/posts",14        "sendQuery": true,15        "queryParameters": {16          "parameters": [17            {18              "name": "query",19              "value": "ai agents"20            }21          ]22        },23        "sendHeaders": true,24        "headerParameters": {25          "parameters": [26            {27              "name": "x-api-key",28              "value": "={{ $env.SOCIALSCRAPE_API_KEY }}"29            }30          ]31        }32      }33    }34  ],35  "connections": {}36}

Example response#

This is a sample from a recorded response, lists and long text are shortened, dash characters in the text are replaced with hyphens. Status 200.

200 OKSample response

1{2  "ok": true,3  "credits_charged": 1,4  "credits_remaining": 4999,5  "cached": false,6  "cached_at": null,7  "request_id": "req_c40c15da8712aea7c04078e6",8  "data": {9    "object": "list",10    "items": [11      {12        "object": "post",13        "platform": "twitter",14        "id": "2089382171291070550",15        "url": "https://x.com/public/status/2089382171291070550",16        "type": "tweet",17        "author": {18          "id": "4875271155",19          "handle": "public",20          "name": "Public",21          "url": "https://x.com/public",22          "avatar_url": "https://pbs.twimg.com/profile_images/2029954921500450820/TM-s7Olp_400x400.png",23          "verified": true24        },25        "title": null,26        "text": "BREAKING: New updates to AI Agents on Public\n\n→ We’ve launched the first-ever marketplace of AI Agents for your portfolio.\n→ Deploy them immediately or customize them.\n→ Share agents you create - with anyone - to run or modify in their account....",27        "published_at": "2026-08-17T16:01:43Z",28        "duration_seconds": 148.356,29        "language": "en",30        "hashtags": null,31        "mentions": null,32        "stats": {33          "views": null,34          "likes": 271,35          "comments": 58,36          "shares": null,37          "saves": null,38          "dislikes": null39        },40        "media": {41          "thumbnail_url": "https://pbs.twimg.com/amplify_video_thumb/2089380922604789760/img/YsvWjEQtSRL1BBVP.jpg",42          "video_url": "https://video.twimg.com/amplify_video/2089380922604789760/vid/avc1/1920x1080/_HrIDXI1YaM9p_0n.mp4",43          "audio_url": null,44          "image_urls": null,45          "width": 1920,46          "height": 108047        },48        "song": null,49        "location": null,50        "is_pinned": null,51        "is_sponsored": null,52        "extra": {53          "is_edited": false,54          "media": [55            {56              "duration_seconds": 148.356,57              "height": 1080,58              "type": "video",59              "url": "https://pbs.twimg.com/amplify_video_thumb/2089380922604789760/img/YsvWjEQtSRL1BBVP.jpg",60              "variants": [61                {62                  "content_type": "application/x-mpegURL",63                  "url": "https://video.twimg.com/amplify_video/2089380922604789760/pl/sILBlF5iBC0thC83.m3u8?v=7c0"64                },65                {66                  "bitrate": 256000,67                  "content_type": "video/mp4",68                  "url": "https://video.twimg.com/amplify_video/2089380922604789760/vid/avc1/480x270/kcwI8ExpuWeSY-m-.mp4"69                },70                {71                  "bitrate": 832000,72                  "content_type": "video/mp4",73                  "url": "https://video.twimg.com/amplify_video/2089380922604789760/vid/avc1/640x360/-n3gU9091zWRTKyv.mp4"74                }75              ],76              "width": 192077            }78          ],79          "possibly_sensitive": false,80          "source_shape": "syndication"81        }82      },83      {84        "object": "post",85        "platform": "twitter",86        "id": "2115190541688398184",87        "url": "https://x.com/AlexTamkin/status/2115190541688398184",88        "type": "tweet",89        "author": {90          "id": "846245360",91          "handle": "AlexTamkin",92          "name": "Alex Tamkin",93          "url": "https://x.com/AlexTamkin",94          "avatar_url": "https://pbs.twimg.com/profile_images/1971860057190207488/UVKmQfr-_400x400.jpg",95          "verified": true96        },97        "title": null,98        "text": "New Anthropic research: How AI agents shape experts' judgment calls\n\nWhen experts delegate work to an agent, do they still make the key decisions? We tested this in a randomized trial with 50 professional data analysts.",99        "published_at": "2026-10-27T21:14:58Z",100        "duration_seconds": 15.0,101        "language": "en",102        "hashtags": null,103        "mentions": null,104        "stats": {105          "views": null,106          "likes": 4257,107          "comments": 314,108          "shares": null,109          "saves": null,110          "dislikes": null111        },112        "media": {113          "thumbnail_url": "https://pbs.twimg.com/amplify_video_thumb/2115181954740187136/img/iRp2D80CClkkY95v.jpg",114          "video_url": "https://video.twimg.com/amplify_video/2115181954740187136/vid/avc1/1600x900/jKk5QaS9zEkshd2n.mp4",115          "audio_url": null,116          "image_urls": null,117          "width": 1600,118          "height": 900119        },120        "song": null,121        "location": null,122        "is_pinned": null,123        "is_sponsored": null,124        "extra": {125          "is_edited": false,126          "media": [127            {128              "duration_seconds": 15.0,129              "height": 900,130              "type": "video",131              "url": "https://pbs.twimg.com/amplify_video_thumb/2115181954740187136/img/iRp2D80CClkkY95v.jpg",132              "variants": [133                {134                  "content_type": "application/x-mpegURL",135                  "url": "https://video.twimg.com/amplify_video/2115181954740187136/pl/jDXVoGQUDPWrcbuS.m3u8"136                },137                {138                  "bitrate": 256000,139                  "content_type": "video/mp4",140                  "url": "https://video.twimg.com/amplify_video/2115181954740187136/vid/avc1/480x270/KSyXPnvgjKX-kAKb.mp4"141                },142                {143                  "bitrate": 832000,144                  "content_type": "video/mp4",145                  "url": "https://video.twimg.com/amplify_video/2115181954740187136/vid/avc1/640x360/H9Ani75NyQGJZ0XQ.mp4"146                }147              ],148              "width": 1600149            }150          ],151          "possibly_sensitive": false,152          "source_shape": "syndication"153        }154      }155    ],156    "cursor": "eyJwIjoyLCJmIjp7InEiOiJhaSBhZ2VudHMgc2l0ZTp4LmNvbSBpbnVybDpzdGF0dXMiLCJzIjoiMTAiLCJuZXh0UGFyYW1zIjoiIiwidiI6ImwiLCJvIjoianNvbiIsImRjIjoiMTEiLCJhcGkiOiJkLmpzIiwidnFkIjoiNC01OTc5NzU0ODc0OTM2MTgxOTEyMDExNjc1NDg2MDgyNTQyNTE2MCIsImtsIjoid3Qtd3Qi...",157    "has_more": true,158    "parent": null159  },160  "cursor": "eyJwIjoyLCJmIjp7InEiOiJhaSBhZ2VudHMgc2l0ZTp4LmNvbSBpbnVybDpzdGF0dXMiLCJzIjoiMTAiLCJuZXh0UGFyYW1zIjoiIiwidiI6ImwiLCJvIjoianNvbiIsImRjIjoiMTEiLCJhcGkiOiJkLmpzIiwidnFkIjoiNC01OTc5NzU0ODc0OTM2MTgxOTEyMDExNjc1NDg2MDgyNTQyNTE2MCIsImtsIjoid3Qtd3Qi...",161  "has_more": true162}

Response#

A list of Post objects in data.items, with data.cursor and data.has_more.

See Data models for every field. The envelope around data is described in Responses.

Errors#

Failures are free: credits_charged is 0. Branch on error.code, never on the message.

Code	HTTP	Retry	Meaning
`invalid_params`	400	no	A parameter is missing, unknown or has the wrong type.
`not_found`	404	no	The platform says this profile, post or item does not exist.
`upstream_blocked`	503	yes	The platform blocked this fetch; retry (a fresh exit is used).

Every request can also fail with the account and platform errors listed on the Errors page.

Example error:

1{2  "ok": false,3  "error": {4    "code": "upstream_blocked",5    "message": "The platform blocked this fetch; retry (a fresh exit is used).",6    "retryable": true7  },8  "credits_charged": 0,9  "request_id": "req_20dfd8488ef13f140433834a"10}

X profile (GET /v1/twitter/profile)
X profile posts (GET /v1/twitter/profile/tweets)
X post details (GET /v1/twitter/tweet)
X video transcript (GET /v1/twitter/tweet/transcript)
X community (GET /v1/twitter/community)
X community posts (GET /v1/twitter/community/tweets)

Parameters#

Example request#

Example response#

Response#

Errors#

Related endpoints#