Twitter Posts API

Endpoint

GET /v1/twitter/posts

Parameters

query *

Search keyword (max 500 characters). Supports X search operators

pages

Number of pages to fetch, 1-20 (default: 1)

sort_by

Sort order: most_recent or relevance (default: most_recent)

posted_ago

Only posts from this period: 1h, 24h, 7d, 30d, 12m (default: all time). Works with both sort orders

start_date

Only posts from this date onward (YYYY-MM-DD, UTC). Not with posted_ago

end_date

Only posts up to and including this date (YYYY-MM-DD, UTC). Not with posted_ago

get_sentiment

Set to true to add AI emotion analysis (+$0.001/page)

Response fields

posts

Array of matching tweets

title

Tweet title (format: @username on X)

url

Direct link to the tweet

date

Publication date and time

author

Twitter username

source

Platform name (Twitter (X))

domain

x.com

snippet

Tweet content text

likes

Number of likes

retweets

Number of retweets

replies

Number of replies

quotes

Number of quote tweets

bookmarks

Number of bookmarks

views

Number of views (null when unavailable)

author_followers

Author's follower count

author_verified

Whether the author is verified

lang

Tweet language code (e.g., en)

is_reply

Whether the tweet is a reply

is_quote

Whether the tweet is a quote tweet

hashtags

Hashtags used in the tweet

user_mentions

Usernames mentioned in the tweet

ai_label

X's "Made with AI" label: has_ai_generated_media (true if the tweet is labelled) and detection_source ("UserDeclared" when the creator added it, "C2paClient" when X detected it from the file). null on the rare results where the label can't be read

sentiment

Emotion analysis: emotions, dominant_emotion, emotional_intensity, polarity (when get_sentiment=true)

pages

Number of pages fetched

count

Total results returned

Example Request

curl "https://apidirect.io/v1/twitter/posts?query=AI&pages=2&sort_by=most_recent" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://apidirect.io/v1/twitter/posts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "query": "AI",
        "pages": 2,
        "sort_by": "most_recent"
    }
)
print(response.json())

Example Response

{
  "posts": [
    {
      "title": "@username on X",
      "url": "https://twitter.com/username/status/...",
      "date": "2024-01-15 14:30:00",
      "author": "username",
      "source": "Twitter (X)",
      "domain": "x.com",
      "snippet": "Tweet content here...",
      "likes": 142,
      "retweets": 38,
      "replies": 12,
      "quotes": 5,
      "bookmarks": 23,
      "views": 18420,
      "author_followers": 5243,
      "author_verified": false,
      "lang": "en",
      "is_reply": false,
      "is_quote": false,
      "hashtags": ["AI", "MachineLearning"],
      "user_mentions": ["OpenAI"],
      "ai_label": {"has_ai_generated_media": false, "detection_source": null},
      "sentiment": {
        "emotions": {
          "joy": 40,
          "trust": 55,
          "fear": 0,
          "surprise": 10,
          "sadness": 0,
          "disgust": 0,
          "anger": 0,
          "anticipation": 30
        },
        "dominant_emotion": "trust",
        "emotional_intensity": 5,
        "polarity": "positive"
      }
    }
  ],
  "pages": 2,
  "count": 40
}

Frequently asked questions

How recent is the data?

The posts are sourced in real-time from Twitter's public search engine, so you can access tweets from the last few years up to the last few seconds.

Can I filter posts by date?

Yes. Use posted_ago for a recent window (1h, 24h, 7d, 30d or 12m), or start_date and end_date (YYYY-MM-DD) for a date range. Both work with either sort order, so sort_by=relevance&posted_ago=24h returns the top posts from the past day.

Does the Twitter Search API include comments and replies?

Yes, the API includes posts, comments and replies. You can use the is_reply field to filter replies from original posts.

What engagement data is included?

Each tweet includes likes, retweets, replies, quotes, bookmarks, and views. You also get author metadata like follower count and verification status. Views may be null for older tweets where this data is unavailable.

How does pricing work?

You only pay for successful requests. The Twitter Posts API costs $0.006 per page. There are no monthly fees or commitments. You get 50 free requests per endpoint every month.

Do I need a credit card to start?

No. You can sign up and use the free tier (50 requests/endpoint/month) without adding a payment method. You only need to add a card when you want to exceed the free tier.

Are there rate limits?

Yes, there's a concurrency limit of 10 simultaneous requests per endpoint per user. If you need more, just get in touch.