// docs

X: Search public posts

Extracts search tweets from X by keyword using Nitter as a public source, with salted hash anonymized author data, text, metrics, links, media and pagination by cursor.

x.com:plp · 1 credit per request

Standard credit cost. Your account pricing is shown in the sandbox.

Try this operation in the sandbox

HTTP request

cURL

curl -X POST https://api.geckoapi.com.br/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "keyword": "openai",
  "target": "x.com",
  "type": "plp",
  "page": 1
}'

Keep your API key on your server. See the quickstart for authentication and response handling.

MCP request

The hosted MCP tool fixes target and type for this operation. Its remaining arguments use the same input rules as Extract.

POST /v1/mcp · Bearer or X-API-Key authentication

x_com_plp · tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "x_com_plp",
    "arguments": {
      "keyword": "openai",
      "page": 1,
      "executionId": "exec_example_123"
    }
  }
}

Supported inputs

Conditional fields depend on the alternatives and constraints in the rule column. Fields marked unsupported are omitted.

Field	Type	Requirement	Rule	Default	Example
keyword Keyword for PLP searches. In Google Search it represents the query sent to Google; in Booking PLP is mandatory; in other PLPs it can replace URL.	string	Required	Mandatory. Represents the search sent to Nitter to find tweets from X.	-	openai
target Target source for extraction.	enum	Required	Always mandatory in the payload and must be x.com.	-	x.com
type Extraction type: pdp, idp, plp, ilp, quote, review or places.	enum	Required	Always mandatory in the payload and must be plp.	-	plp
page Pagination. In PLP, including Trivago, and in Reclame AQUI ILP starts in 1; in review (MercadoLivre, Booking and Hotels) starts in 0. The Reclame AQUI ILP even accepts the page 100.	integer	Optional	Tweet page (entire from 1 to 10). As Nitter uses cursor, the backend walks the cursors to the requested page.	1	1

Request examples

Search for tweets - first page

Recommended flow; only send keyword and page. The URL of the Nitter is automatically assembled by the backend.

Search for tweets - first page

{
  "keyword": "openai",
  "target": "x.com",
  "type": "plp",
  "page": 1
}

Search for tweets - page 2

The backend internally browses cursor from Nitter to return older tweets from the same keyword.

Search for tweets - page 2

{
  "keyword": "openai",
  "target": "x.com",
  "type": "plp",
  "page": 2
}

Response schema

Leaf paths and expected types. Field names and enum values are part of the API contract.

responseSchema

{
  "requestId": "string (uuid)",
  "executionId": "string (uuid)",
  "notFound": "boolean (optional; true when the upstream entity was not found and data is null)",
  "data.source": "string",
  "data.provider": "string",
  "data.type": "string",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.searchUrl": "string",
  "data.extractedAt": "string (iso datetime)",
  "data.query": "string",
  "data.page": "number",
  "data.resultsPerPage": "number",
  "data.offset": "number",
  "data.primaryResults": "number",
  "data.totalResults": "number | null",
  "data.hasMore": "boolean",
  "data.nextPage": "number | null",
  "data.nextPageUrl": "string | null",
  "data.nextCursor": "string | null",
  "data.exhaustedBeforePage": "boolean",
  "data.items[].position": "number",
  "data.items[].id": "string | null",
  "data.items[].url": "string | null",
  "data.items[].nitterUrl": "string",
  "data.items[].author.username": "string | null",
  "data.items[].author.handle": "string | null",
  "data.items[].author.displayName": "string | null",
  "data.items[].author.profileUrl": "string | null",
  "data.items[].author.nitterProfileUrl": "string | null",
  "data.items[].author.avatarUrl": "string | null",
  "data.items[].author.verified": "boolean",
  "data.items[].author.verifiedType": "string | null",
  "data.items[].publishedAt": "string | null",
  "data.items[].publishedAtRaw": "string | null",
  "data.items[].relativeTime": "string | null",
  "data.items[].text": "string | null",
  "data.items[].contentHtml": "string | null",
  "data.items[].retweetedBy": "string | null",
  "data.items[].replyTo[]": "string",
  "data.items[].hashtags[]": "string",
  "data.items[].mentions[]": "string",
  "data.items[].links[].url": "string",
  "data.items[].links[].text": "string | null",
  "data.items[].media[].type": "string",
  "data.items[].media[].url": "string | null",
  "data.items[].media[].thumbnailUrl": "string | null",
  "data.items[].media[].altText": "string | null",
  "data.items[].stats.comments": "number",
  "data.items[].stats.retweets": "number",
  "data.items[].stats.quotes": "number",
  "data.items[].stats.likes": "number",
  "data.items[].stats.views": "number"
}

Example response

Illustrative response. Product names, reviews and other source content retain their original language. Missing and null values do not imply zero stock, free shipping or zero reviews.

responseExample

{
  "requestId": "req_01HZXAMPLE0000000000000000",
  "executionId": "exec_01HZXAMPLE0000000000000000",
  "notFound": false,
  "data": {
    "source": "x.com",
    "provider": "nitter.net",
    "type": "plp",
    "url": "https://nitter.net/search?f=tweets&q=openai",
    "requestUrl": "https://nitter.net/search?f=tweets&q=openai",
    "searchUrl": "https://nitter.net/search?f=tweets&q=openai",
    "extractedAt": "2026-05-17T14:45:30.000Z",
    "query": "openai",
    "page": 1,
    "resultsPerPage": 20,
    "offset": 0,
    "primaryResults": 20,
    "totalResults": 0,
    "hasMore": true,
    "nextPage": 2,
    "nextPageUrl": "https://nitter.net/search?f=tweets&q=openai&cursor=DAADDAABCgABExample",
    "nextCursor": "DAADDAABCgABExample",
    "exhaustedBeforePage": false,
    "items": [
      {
        "position": 1,
        "id": "tweet_8f65c0d6a71b2e34",
        "url": "x://tweet/tweet_8f65c0d6a71b2e34",
        "nitterUrl": "nitter://tweet/tweet_8f65c0d6a71b2e34",
        "author": {
          "username": "user_4b1d2f90a63c5e18",
          "handle": "@user_4b1d2f90a63c5e18",
          "displayName": "display_2d8ad6a2f4c901ef",
          "profileUrl": "x://user/user_4b1d2f90a63c5e18",
          "nitterProfileUrl": "nitter://user/user_4b1d2f90a63c5e18",
          "avatarUrl": "avatar_a4bfe91c8842d70e",
          "verified": true,
          "verifiedType": "Verified blue account"
        },
        "publishedAt": "2026-05-17T14:45:00.000Z",
        "publishedAtRaw": "May 17, 2026 · 2:45 PM UTC",
        "relativeTime": "24s",
        "text": "Building with #OpenAI and url_02fdcfb7d67c7c80",
        "contentHtml": "Building with <a href=\"link_3b7e588a5e9f2450\">#OpenAI</a> and <a href=\"link_8c305bbd1bd38ff3\">url_02fdcfb7d67c7c80</a>",
        "retweetedBy": "retweet_223f1c6c5d9c4b80",
        "replyTo": [
          "@user_94c47df2cbbf2f93"
        ],
        "hashtags": [
          "#OpenAI"
        ],
        "mentions": [
          "@user_94c47df2cbbf2f93"
        ],
        "links": [
          {
            "url": "link_3b7e588a5e9f2450",
            "text": "#OpenAI"
          },
          {
            "url": "link_8c305bbd1bd38ff3",
            "text": "link_text_0ea8d4aa9c1b2a64"
          }
        ],
        "media": [
          {
            "type": "image",
            "url": "media_76652f4f2ec86107",
            "thumbnailUrl": "thumbnail_b216bdb83a8caa91",
            "altText": "alt_458e56f647245215"
          }
        ],
        "stats": {
          "comments": 2,
          "retweets": 3,
          "quotes": 0,
          "likes": 4,
          "views": 1200
        }
      }
    ]
  }
}

Complete field reference

Path	Type	Description	Example
data.exhaustedBeforePage	boolean	Indicates that the requested page was beyond the last available cursor.	false
data.extractedAt	string (iso datetime)	Extraction timestamp ISO.	2026-05-17T14:45:30.000Z
data.hasMore	boolean	Indicates whether there is cursor to load older tweets.	true
data.items[].author.avatarUrl	string \| null	Avatar pseudonym token.	avatar_a4bfe91c8842d70e
data.items[].author.displayName	string \| null	Pseudonym token of the displayed name.	display_2d8ad6a2f4c901ef
data.items[].author.handle	string \| null	Author pseudonym token with @.	@user_4b1d2f90a63c5e18
data.items[].author.nitterProfileUrl	string \| null	Pseudonymous reference of the profile in Nitter.	nitter://user/user_4b1d2f90a63c5e18
data.items[].author.profileUrl	string \| null	Pseudonymous reference of the profile in x.com.	x://user/user_4b1d2f90a63c5e18
data.items[].author.username	string \| null	Author pseudonym token without @.	user_4b1d2f90a63c5e18
data.items[].author.verified	boolean	Indicates whether the Nitter markup shows a verification seal.	true
data.items[].author.verifiedType	string \| null	Check text/type when available.	Verified blue account
data.items[].contentHtml	string \| null	HTML of tweet content with anonymized hrefs and identifiers.	Building with <a href="link_3b7e588a5e9f2450">#OpenAI</a> and <a href="link_8c305bbd1bd38ff3">url_02fdcfb7d67c7c80</a>
data.items[].hashtags[]	string	Hashtags found in the content.	#OpenAI
data.items[].id	string \| null	Tweet token generated by salted hash of ID/original path.	tweet_8f65c0d6a71b2e34
data.items[].links[].text	string \| null	Text displayed for the link, with anonymized URLs and identifiers.	#OpenAI
data.items[].links[].url	string	Link pseudonym token present in the content.	link_3b7e588a5e9f2450
data.items[].media[].altText	string \| null	Alternative text pseudonym token when available.	alt_458e56f647245215
data.items[].media[].thumbnailUrl	string \| null	Thumbnail pseudonym token when available.	thumbnail_b216bdb83a8caa91
data.items[].media[].type	string	Media type detected.	image
data.items[].media[].url	string \| null	Media pseudonym token.	media_76652f4f2ec86107
data.items[].mentions[]	string	Pseudonymous mentions found in the content.	@user_94c47df2cbbf2f93
data.items[].nitterUrl	string	Pseudonymous reference equivalent to Nitter; does not contain username or raw ID.	nitter://tweet/tweet_8f65c0d6a71b2e34
data.items[].position	number	Position of the tweet in the returned pagination.	1
data.items[].publishedAt	string \| null	Date ISO of the tweet when Nitter provides parseable title.	2026-05-17T14:45:00.000Z
data.items[].publishedAtRaw	string \| null	Original date displayed in the title of Nitter.	May 17, 2026 · 2:45 PM UTC
data.items[].relativeTime	string \| null	Relative time displayed by Nitter.	24s
data.items[].replyTo[]	string	Pseudonymous handles cited by the reply block.	@user_94c47df2cbbf2f93
data.items[].retweetedBy	string \| null	Retweet pseudonym token when the item is a retweet.	retweet_223f1c6c5d9c4b80
data.items[].stats.comments	number	Number of comments displayed by Nitter.	2
data.items[].stats.likes	number	Number of likes displayed by Nitter.	4
data.items[].stats.quotes	number	Number of quotes displayed by Nitter.	0
data.items[].stats.retweets	number	Number of retweets displayed by Nitter.	3
data.items[].stats.views	number	Number of views displayed by Nitter.	1200
data.items[].text	string \| null	Clean tweet text with handles, emails, URLs and long identifiers anonymized by salted hash.	Building with #OpenAI and url_02fdcfb7d67c7c80
data.items[].url	string \| null	Pseudonymous reference equivalent to x.com; does not contain username or raw ID.	x://tweet/tweet_8f65c0d6a71b2e34
data.nextCursor	string \| null	Cursor Nitter extracted from the Load more link.	DAADDAABCgABExample
data.nextPage	number \| null	Next numeric page that can be requested.	2
data.nextPageUrl	string \| null	URL Nitter with cursor to the next page.	https://nitter.net/search?f=tweets&q=openai&cursor=DAADDAABCgABExample
data.offset	number	Estimated offset considering 20 tweets per page of Nitter.	0
data.page	number	Page requested.	1
data.primaryResults	number	Quantity of main items returned.	20
data.provider	string	Site used to read public tweets.	nitter.net
data.query	string	Keyword searched.	openai
data.requestUrl	string	Same value as `data.url`; never exposes the queried internal endpoint.	https://nitter.net/search?f=tweets&q=openai
data.resultsPerPage	number	Number of tweets returned on this page.	20
data.searchUrl	string	URL initial search in Nitter.	https://nitter.net/search?f=tweets&q=openai
data.source	string	Public source exposed by API.	x.com
data.totalResults	number \| null	Total results when available; Nitter does not provide complete reliability.	0
data.type	string	Type of API, always plp.	plp
data.url	string	URL actually used for the returned page.	https://nitter.net/search?f=tweets&q=openai
executionId	string (uuid)	Execution identifier used by the gateway.	exec_01HZXAMPLE0000000000000000
notFound	boolean (optional; true when the upstream entity was not found and data is null)	Present is true when the upstream entity was not found.	false
requestId	string (uuid)	Unique identifier of the request.	req_01HZXAMPLE0000000000000000

Errors and missing data

When supported by this operation, an entity not found upstream can return HTTP 200 with data: null and notFound: true. Check the documented response fields before interpreting an empty result. Source-specific behavior and exceptions are described above.

HTTP status	Error code	Meaning
400	`INVALID_PAYLOAD`	Invalid JSON or a request that violates the documented validation rules.
401	`UNAUTHORIZED`	Missing authorization or an invalid API key or token.
402	`INSUFFICIENT_CREDITS`	The account has insufficient credits for this operation.
403	`FORBIDDEN`	The account does not have access, or the API is temporarily disabled.
409	`EXECUTION_CONFLICT`	The execution identifier conflicts with an incompatible execution state.
429	`RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTS`	A rate limit or simultaneous request limit was exceeded.
5xx	`UPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_FUNCTION_ERROR`	An upstream, worker or gateway failure. Failed requests follow the platform refund policy.