X post search

Beta GET /v1/twitter/search/posts

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
Status: Beta. Built and tested against recorded responses; the shape may still gain fields.
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).

curl

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

Python

import os
import requests

params = {
    "query": "ai agents",
}
res = requests.get(
    "https://api.socialscrape.io/v1/twitter/search/posts",
    headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},
    params=params,
)
body = res.json()

if body["ok"]:
    print(body["data"])
else:
    print(body["error"]["code"], body["error"]["message"])

TypeScript

const url = new URL("https://api.socialscrape.io/v1/twitter/search/posts");
url.search = new URLSearchParams({
  "query": "ai agents"
}).toString();
const res = await fetch(url, {
  headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },
});
const body = await res.json();

if (body.ok) {
  console.log(body.data);
} else {
  console.error(body.error.code, body.error.message);
}

n8n

{
  "nodes": [
    {
      "name": "SocialScrape X post search",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        0,
        0
      ],
      "parameters": {
        "method": "GET",
        "url": "https://api.socialscrape.io/v1/twitter/search/posts",
        "sendQuery": true,
        "queryParameters": {
          "parameters": [
            {
              "name": "query",
              "value": "ai agents"
            }
          ]
        },
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "x-api-key",
              "value": "={{ $env.SOCIALSCRAPE_API_KEY }}"
            }
          ]
        }
      }
    }
  ],
  "connections": {}
}

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.

{
  "ok": true,
  "credits_charged": 1,
  "credits_remaining": 4999,
  "cached": false,
  "cached_at": null,
  "request_id": "req_c40c15da8712aea7c04078e6",
  "data": {
    "object": "list",
    "items": [
      {
        "object": "post",
        "platform": "twitter",
        "id": "2089382171291070550",
        "url": "https://x.com/public/status/2089382171291070550",
        "type": "tweet",
        "author": {
          "id": "4875271155",
          "handle": "public",
          "name": "Public",
          "url": "https://x.com/public",
          "avatar_url": "https://pbs.twimg.com/profile_images/2029954921500450820/TM-s7Olp_400x400.png",
          "verified": true
        },
        "title": null,
        "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....",
        "published_at": "2026-08-17T16:01:43Z",
        "duration_seconds": 148.356,
        "language": "en",
        "hashtags": null,
        "mentions": null,
        "stats": {
          "views": null,
          "likes": 271,
          "comments": 58,
          "shares": null,
          "saves": null,
          "dislikes": null
        },
        "media": {
          "thumbnail_url": "https://pbs.twimg.com/amplify_video_thumb/2089380922604789760/img/YsvWjEQtSRL1BBVP.jpg",
          "video_url": "https://video.twimg.com/amplify_video/2089380922604789760/vid/avc1/1920x1080/_HrIDXI1YaM9p_0n.mp4",
          "audio_url": null,
          "image_urls": null,
          "width": 1920,
          "height": 1080
        },
        "song": null,
        "location": null,
        "is_pinned": null,
        "is_sponsored": null,
        "extra": {
          "is_edited": false,
          "media": [
            {
              "duration_seconds": 148.356,
              "height": 1080,
              "type": "video",
              "url": "https://pbs.twimg.com/amplify_video_thumb/2089380922604789760/img/YsvWjEQtSRL1BBVP.jpg",
              "variants": [
                {
                  "content_type": "application/x-mpegURL",
                  "url": "https://video.twimg.com/amplify_video/2089380922604789760/pl/sILBlF5iBC0thC83.m3u8?v=7c0"
                },
                {
                  "bitrate": 256000,
                  "content_type": "video/mp4",
                  "url": "https://video.twimg.com/amplify_video/2089380922604789760/vid/avc1/480x270/kcwI8ExpuWeSY-m-.mp4"
                },
                {
                  "bitrate": 832000,
                  "content_type": "video/mp4",
                  "url": "https://video.twimg.com/amplify_video/2089380922604789760/vid/avc1/640x360/-n3gU9091zWRTKyv.mp4"
                }
              ],
              "width": 1920
            }
          ],
          "possibly_sensitive": false,
          "source_shape": "syndication"
        }
      },
      {
        "object": "post",
        "platform": "twitter",
        "id": "2115190541688398184",
        "url": "https://x.com/AlexTamkin/status/2115190541688398184",
        "type": "tweet",
        "author": {
          "id": "846245360",
          "handle": "AlexTamkin",
          "name": "Alex Tamkin",
          "url": "https://x.com/AlexTamkin",
          "avatar_url": "https://pbs.twimg.com/profile_images/1971860057190207488/UVKmQfr-_400x400.jpg",
          "verified": true
        },
        "title": null,
        "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.",
        "published_at": "2026-10-27T21:14:58Z",
        "duration_seconds": 15.0,
        "language": "en",
        "hashtags": null,
        "mentions": null,
        "stats": {
          "views": null,
          "likes": 4257,
          "comments": 314,
          "shares": null,
          "saves": null,
          "dislikes": null
        },
        "media": {
          "thumbnail_url": "https://pbs.twimg.com/amplify_video_thumb/2115181954740187136/img/iRp2D80CClkkY95v.jpg",
          "video_url": "https://video.twimg.com/amplify_video/2115181954740187136/vid/avc1/1600x900/jKk5QaS9zEkshd2n.mp4",
          "audio_url": null,
          "image_urls": null,
          "width": 1600,
          "height": 900
        },
        "song": null,
        "location": null,
        "is_pinned": null,
        "is_sponsored": null,
        "extra": {
          "is_edited": false,
          "media": [
            {
              "duration_seconds": 15.0,
              "height": 900,
              "type": "video",
              "url": "https://pbs.twimg.com/amplify_video_thumb/2115181954740187136/img/iRp2D80CClkkY95v.jpg",
              "variants": [
                {
                  "content_type": "application/x-mpegURL",
                  "url": "https://video.twimg.com/amplify_video/2115181954740187136/pl/jDXVoGQUDPWrcbuS.m3u8"
                },
                {
                  "bitrate": 256000,
                  "content_type": "video/mp4",
                  "url": "https://video.twimg.com/amplify_video/2115181954740187136/vid/avc1/480x270/KSyXPnvgjKX-kAKb.mp4"
                },
                {
                  "bitrate": 832000,
                  "content_type": "video/mp4",
                  "url": "https://video.twimg.com/amplify_video/2115181954740187136/vid/avc1/640x360/H9Ani75NyQGJZ0XQ.mp4"
                }
              ],
              "width": 1600
            }
          ],
          "possibly_sensitive": false,
          "source_shape": "syndication"
        }
      }
    ],
    "cursor": "eyJwIjoyLCJmIjp7InEiOiJhaSBhZ2VudHMgc2l0ZTp4LmNvbSBpbnVybDpzdGF0dXMiLCJzIjoiMTAiLCJuZXh0UGFyYW1zIjoiIiwidiI6ImwiLCJvIjoianNvbiIsImRjIjoiMTEiLCJhcGkiOiJkLmpzIiwidnFkIjoiNC01OTc5NzU0ODc0OTM2MTgxOTEyMDExNjc1NDg2MDgyNTQyNTE2MCIsImtsIjoid3Qtd3Qi...",
    "has_more": true,
    "parent": null
  },
  "cursor": "eyJwIjoyLCJmIjp7InEiOiJhaSBhZ2VudHMgc2l0ZTp4LmNvbSBpbnVybDpzdGF0dXMiLCJzIjoiMTAiLCJuZXh0UGFyYW1zIjoiIiwidiI6ImwiLCJvIjoianNvbiIsImRjIjoiMTEiLCJhcGkiOiJkLmpzIiwidnFkIjoiNC01OTc5NzU0ODc0OTM2MTgxOTEyMDExNjc1NDg2MDgyNTQyNTE2MCIsImtsIjoid3Qtd3Qi...",
  "has_more": true
}

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:

{
  "ok": false,
  "error": {
    "code": "upstream_blocked",
    "message": "The platform blocked this fetch; retry (a fresh exit is used).",
    "retryable": true
  },
  "credits_charged": 0,
  "request_id": "req_20dfd8488ef13f140433834a"
}

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)

Get started

Guides

API reference

Resources

X post search

Parameters#

Example request#

Example response#

Response#

Errors#

Get started

Guides

API reference

Resources

X post search

Parameters#

Example request#

Example response#

Response#

Errors#

Related endpoints#