X / Twitter

Search / Trends

per_call

Runs search across X posts with support for operators, result type (top/latest) and language filters, and returns trending topic lists with post volumes for a given location. Built for real-time monitoring and trend research.

What you get

Each call returns up to 20 tweets, plus a cursor for the next 20.

Endpoint

GET /v1/x/search-trends

Price

$4.50

per 1,000 calls · $0.0045 per call

Cost per call

3 credits

Failed calls never charged

Parameters

target

required

string

The X / Twitter handle, URL or identifier to resolve.

limit

optional

integer

Maximum records to return, capped at this service's page size (see Limits below). Omit it to receive the whole page. It shapes the response, not the price — a call costs the same either way.

cursor

optional

string

Pagination cursor returned by a previous response.

fresh

optional

enum

Bypass cached data and force a live fetch for this one call. Use it for daily monitoring or any figure you are tracking over time. Accepts `true`, `1`, `false` or `0`; anything else returns 400 `invalid_fresh`. Defaults to false and costs exactly the same as a cached call.

One of: true, 1, false, 0

Example request

Live call. Successful calls are charged; failed and empty results are not.

curl

curl "https://fastfetchz.com/v1/x/search-trends?target=nasa" \
  -H "X-API-Key: $FASTFETCHZ_KEY"

Example response

200 application/json

{
  "success": true,
  "service": {
    "platform": "X / Twitter",
    "name": "Search / Trends",
    "slug": "search-trends"
  },
  "credits_charged": 3,
  "credits_remaining": 97,
  "latency_ms": 214,
  "data": {
    "items": [
      {
        "type": "tweet",
        "id": "2097416221599932777",
        "url": "https://x.com/tweetthisjay/status/2097416221599932777",
        "twitterUrl": "https://twitter.com/tweetthisjay/status/2097416221599932777",
        "text": "@BedBathandNDA So space call Saturday?",
        "source": "Twitter for iPhone",
        "retweetCount": 0,
        "replyCount": 0,
        "likeCount": 0,
        "quoteCount": 0,
        "viewCount": 0,
        "createdAt": "Tue Sep 08 20:06:09 +0000 2026",
        "lang": "en",
        "bookmarkCount": 0,
        "isReply": true,
        "inReplyToId": "2097412615379022004",
        "conversationId": "2097412615379022004",
        "displayTextRange": [
          15,
          38
        ],
        "inReplyToUserId": "2045124402644156416",
        "inReplyToUsername": "BedBathandNDA",
        "author": {
          "type": "user",
          "userName": "tweetthisjay",
          "url": "https://x.com/tweetthisjay",
          "twitterUrl": "https://twitter.com/tweetthisjay",
          "id": "1430728613372973056",
          "name": "tweetthisjay",
          "isVerified": false,
          "isBlueVerified": false,
          "verifiedType": null,
          "profilePicture": "https://pbs.twimg.com/profile_images/2089601560200515584/xtgnVDkS_normal.jpg",
          "coverPicture": "",
          "description": "",
          "location": "",
          "followers": 172,
          "following": 255,
          "status": "",
          "canDm": false,
          "canMediaTag": true,
          "createdAt": "Thu Aug 26 03:08:52 +0000 2021",
          "entities": {
            "description": {
              "urls": []
            },
            "url": {}
          },
          "fastFollowersCount": 0,
          "favouritesCount": 11849,
          "hasCustomTimelines": true,
          "isTranslator": false,
          "mediaCount": 319,
          "statusesCount": 3237,
          "withheldInCountries": [],
          "affiliatesHighlightedLabel": {},
          "possiblySensitive": false,
          "pinnedTweetIds": [],
          "profile_bio": {
            "description": "Just browsing.....",
            "entities": {
              "description": {}
            }
          },
          "isAutomated": false,
          "automatedBy": null
        },
        "extendedEntities": {},
        "card": null,
        "place": {},
        "entities": {
          "user_mentions": [
            {
              "id_str": "2045124402644156416",
              "indices": [
                0,
                14
              ],
              "name": "BedBathandNDA",
              "screen_name": "BedBathandNDA"
            }
          ]
        },
        "quoted_tweet": null,
        "retweeted_tweet": null,
        "isLimitedReply": false,
        "communityInfo": null,
        "article": null
      },
      {
        "type": "tweet",
        "id": "2097416182135411159",
        "url": "https://x.com/ayodejionline/status/2097416182135411159",
        "twitterUrl": "https://twitter.com/ayodejionline/status/2097416182135411159",
        "text": "@cryptichybee My mum was has at luth on Friday 4th September 2026 and was told no bed space and she was brought back home. Please keep quiet and face front. Sometimes I wonder how much they are paying you guys",
        "source": "Twitter for iPhone",
        "retweetCount": 0,
        "replyCount": 0,
        "likeCount": 0,
        "quoteCount": 0,
        "viewCount": 0,
        "createdAt": "Tue Sep 08 20:06:00 +0000 2026",
        "lang": "en",
        "bookmarkCount": 0,
        "isReply": true,
        "inReplyToId": "2097233914246873467",
        "conversationId": "2097233914246873467",
        "displayTextRange": [
          14,
          209
        ],
        "inReplyToUserId": "191870387",
        "inReplyToUsername": "cryptichybee",
        "author": {
          "type": "user",
          "userName": "ayodejionline",
          "url": "https://x.com/ayodejionline",
          "twitterUrl": "https://twitter.com/ayodejionline",
          "id": "201164691",
          "name": "A Blanco",
          "isVerified": false,
          "isBlueVerified": false,
          "verifiedType": null,
          "profilePicture": "https://pbs.twimg.com/profile_images/1998151995807399936/akQStXuk_normal.jpg",
          "coverPicture": "https://pbs.twimg.com/profile_banners/201164691/1603234909",
          "description": "",
          "location": "Lagos, Nigeria",
          "followers": 169,
          "following": 652,
          "status": "",
          "canDm": true,
          "canMediaTag": true,
          "createdAt": "Mon Oct 11 06:55:34 +0000 2010",
          "entities": {
            "description": {
              "urls": []
            },
            "url": {}
          },
          "fastFollowersCount": 0,
          "favouritesCount": 6937,
          "hasCustomTimelines": true,
          "isTranslator": false,
          "mediaCount": 837,
          "statusesCount": 10743,
          "withheldInCountries": [],
          "affiliatesHighlightedLabel": {},
          "possiblySensitive": false,
          "pinnedTweetIds": [],
          "profile_bio": {
            "description": "AYODEJI, humble and kind. Real Estate/Banking/Football, An advocate of Common sense....... God over everything.",
            "entities": {
              "description": {}
            }
          },
          "isAutomated": false,
          "automatedBy": null
        },
        "extendedEntities": {},
        "card": null,
        "place": {},
        "entities": {
          "user_mentions": [
            {
              "id_str": "191870387",
              "indices": [
                0,
                13
              ],
              "name": "Cryptic Hybee",
              "screen_name": "cryptichybee"
            }
          ]
        },
        "quoted_tweet": null,
        "retweeted_tweet": null,
        "isLimitedReply": false,
        "communityInfo": null,
        "article": null
      }
    ],
    "result_key": "tweets",
    "has_next_page": true,
    "next_cursor": "DAADDAABCgABHRuE8OKbIWkKAAIdG4TTDBdxWwAIAAIAAAACCAADAAAAAAgABAAAAAAKAAUdG4T07EAnEAoABh0bhPTsP9jwCwAHAAAA8EVtUEM2d0FBQWZRL2dHSk4wdkdwL0FBQUFCUWRHNFRlMFp2Uk5CMGJoTml3bDRIRUhSdUUyYmFiSVdZZEc0VGdWeGRCcHgwYmhPYjdsb0Z3SFJ1RTFYSldNSjhkRzRUY1l4YlIxeDBiaE4vODFtQndIUnVFMHd3WGNWc2RHNFRpQnhaQW9CMGJoT005RnZHd0hSdUUwekVYQVBNZEc0VFZZRmF4ZWgwYmhOKzhWekFuSFJ1RTQwcGJJUkVkRzRUdzRwc2hhUjBiaE5VZ1duSHlIUnVFNTdKV1VkY2RH…"
  }
}

Getting more results

Each response includes a cursor. Pass it back as cursor to fetch the next 20 tweets. Repeat until no cursor is returned.

two calls

# Call 1 — first 20 tweets
curl "https://fastfetchz.com/v1/x/search-trends?target=nasa" \
  -H "X-API-Key: $FASTFETCHZ_KEY"
# -> { "data": { ... }, "cursor": "eyJwYWdlIjoyfQ" }

# Call 2 — next 20 tweets
curl "https://fastfetchz.com/v1/x/search-trends?target=nasa&cursor=eyJwYWdlIjoyfQ" \
  -H "X-API-Key: $FASTFETCHZ_KEY"

Limits

Maximum per call: 20 tweets.
Minimum per call: 1 tweet — a target with less data returns fewer tweets, and an empty result is still a successful call.
Each call fetches a full page of up to 20 and costs the same either way. Pass limit to receive fewer than that in the response.
Larger jobs are paginated with a cursor; there is no cap on how many pages you fetch.

What this costs in practice

200,000 tweets = 10,000 calls × 3 credits per call = 30,000 credits = $0.00

Priced at the Custom pack rate: 1,000,000 credits for $0.00.

Open in the pricing calculator

Error codes

StatusCodeMeaning

401invalid_api_keyMissing or unrecognized X-API-Key header. No credits are charged.

402insufficient_creditsYour balance is below the cost of the call. Top up to continue.

403account_suspended / key_revokedThe account is suspended or the key was revoked.

429rate_limitedOver your account's requests-per-second limit. Retrying helps: the body carries retry_after_seconds and the response carries a Retry-After header. Not charged.

429monthly_cap_reachedThis key used the monthly call cap you set for it. Retrying will not help — raise the cap, use another key, or wait for the next calendar month. No Retry-After header is sent. Not charged.

500upstream_errorUnexpected failure while fulfilling the request. Not charged.