Configure Harness

X Search API

Search X users, tweets, timelines, and replies with pagination metadata.

POST/v2/x/tweet/search

Authentication

Bearer API key

Content type

application/json

Rate notes

1 request per 10 seconds, 3 per minute, 10 per 10 minutes.

Chat API

The X Search API provides access to X (Twitter) data, including user profiles, tweet search, user tweets, and tweet replies.

Authentication

All requests require an API Key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

1. Get User Info

Batch retrieve X user profiles by username.

Endpoint

POST https://openapi.felo.ai/v2/x/user/info

Request Body

Parameter	Type	Required	Description
`usernames`	array of strings	Yes	List of X usernames to look up

Example

curl -X POST 'https://openapi.felo.ai/v2/x/user/info' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "usernames": ["elonmusk", "OpenAI"]
  }'

Success Response (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 2,
    "users": [
      {
        "user_id": "44196397",
        "username": "elonmusk",
        "display_name": "Elon Musk",
        "description": "...",
        "followers_count": 100000000,
        "following_count": 500,
        "tweet_count": 30000,
        "verified": true,
        "blue_verified": true,
        "profile_image_url": "https://pbs.twimg.com/...",
        "created_at": "2009-06-02T00:00:00Z",
        "location": "Mars"
      }
    ]
  }
}

User Object Fields

Field	Type	Description
`user_id`	string	X user ID
`username`	string	X handle (without @)
`display_name`	string	Display name
`description`	string	User bio
`followers_count`	integer	Number of followers
`following_count`	integer	Number of following
`tweet_count`	integer	Total tweets
`verified`	boolean	Whether the account is verified
`blue_verified`	boolean	Whether the account has Blue verification
`verified_type`	string	Verification type
`profile_image_url`	string	Profile image URL
`cover_image_url`	string	Cover image URL
`created_at`	string	Account creation time
`location`	string	User location
`url`	string	User website URL
`protected`	boolean	Whether the account is protected
`favorites_count`	integer	Number of likes
`media_count`	integer	Number of media posts
`can_dm`	boolean	Whether DM is open
`is_automated`	boolean	Whether the account is automated
`pinned_tweet_ids`	array of strings	Pinned tweet IDs

2. Search Users

Search X users by keyword.

Endpoint

POST https://openapi.felo.ai/v2/x/user/search

Request Body

Parameter	Type	Required	Description
`query`	string	Yes	Search keyword
`cursor`	string	No	Pagination cursor from previous response

Example

curl -X POST 'https://openapi.felo.ai/v2/x/user/search' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "artificial intelligence"
  }'

Success Response (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 50,
    "has_next": true,
    "next_cursor": "cursor_abc123",
    "users": [
      {
        "user_id": "...",
        "username": "...",
        "display_name": "..."
      }
    ]
  }
}

Response Fields

Field	Type	Description
`total`	integer	Total number of results
`has_next`	boolean	Whether more results are available
`next_cursor`	string	Cursor for next page
`users`	array	List of user objects (see section 1)

3. Get User Tweets

Retrieve tweets from a specific X user.

Endpoint

POST https://openapi.felo.ai/v2/x/user/tweets

Request Body

Parameter	Type	Required	Description
`x_user_id`	string	No	X user ID (provide either `x_user_id` or `username`)
`username`	string	No	X username (provide either `x_user_id` or `username`)
`limit`	integer	No	Number of tweets to return
`cursor`	string	No	Pagination cursor
`include_replies`	boolean	No	Whether to include replies

Example

curl -X POST 'https://openapi.felo.ai/v2/x/user/tweets' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "elonmusk",
    "limit": 20
  }'

Success Response (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 20,
    "has_next": true,
    "next_cursor": "cursor_def456",
    "tweets": [
      {
        "id": "1234567890",
        "content": "Tweet content here...",
        "author": { "user_id": "...", "username": "elonmusk" },
        "created_at": "2026-03-09T12:00:00Z",
        "metrics": {
          "retweet_count": 1000,
          "favorite_count": 5000,
          "reply_count": 200,
          "quote_count": 100,
          "view_count": 500000,
          "bookmark_count": 50
        },
        "hashtags": ["AI"],
        "mentions": ["OpenAI"],
        "url": "https://x.com/elonmusk/status/1234567890",
        "lang": "en"
      }
    ]
  }
}

Tweet Object Fields

Field	Type	Description
`id`	string	Tweet ID
`content`	string	Tweet text content
`author`	object	Author user object (see section 1)
`created_at`	string	Tweet creation time
`metrics`	object	Engagement metrics (see below)
`replies`	array	Reply tweets (if available)
`conversation_id`	string	Conversation thread ID
`media_urls`	array	Attached media
`hashtags`	array of strings	Hashtags in the tweet
`mentions`	array of strings	Mentioned usernames
`urls`	array of strings	URLs in the tweet
`url`	string	Permalink to the tweet
`source`	string	Tweet source (e.g. "Twitter Web App")
`lang`	string	Tweet language code
`is_reply`	boolean	Whether this is a reply
`in_reply_to_id`	string	ID of the tweet being replied to
`in_reply_to_user_id`	string	User ID of the tweet being replied to
`in_reply_to_username`	string	Username of the tweet being replied to
`quoted_tweet`	object	Quoted tweet object (recursive)
`retweeted_tweet`	object	Retweeted tweet object (recursive)
`is_limited_reply`	boolean	Whether replies are limited

Metrics Object Fields

Field	Type	Description
`retweet_count`	integer	Number of retweets
`favorite_count`	integer	Number of likes
`reply_count`	integer	Number of replies
`quote_count`	integer	Number of quotes
`view_count`	integer	Number of views
`bookmark_count`	integer	Number of bookmarks

4. Search Tweets

Search X tweets by keyword with advanced query support.

Endpoint

POST https://openapi.felo.ai/v2/x/tweet/search

Request Body

Parameter	Type	Required	Description
`query`	string	Yes	Search query (supports advanced search syntax)
`query_type`	string	No	Query type filter
`since_time`	integer	No	Start time filter (Unix timestamp in seconds)
`until_time`	integer	No	End time filter (Unix timestamp in seconds)
`limit`	integer	No	Number of tweets to return
`cursor`	string	No	Pagination cursor

Example

curl -X POST 'https://openapi.felo.ai/v2/x/tweet/search' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "artificial intelligence",
    "limit": 20
  }'

Success Response (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 20,
    "has_next": true,
    "next_cursor": "cursor_ghi789",
    "tweets": [
      {
        "id": "...",
        "content": "...",
        "author": { "user_id": "...", "username": "..." },
        "created_at": "2026-03-09T12:00:00Z",
        "metrics": { "retweet_count": 100, "favorite_count": 500 }
      }
    ]
  }
}

Response Fields

Field	Type	Description
`total`	integer	Total number of results
`has_next`	boolean	Whether more results are available
`next_cursor`	string	Cursor for next page
`tweets`	array	List of tweet objects (see section 3)

5. Get Tweet Replies

Retrieve replies for specific tweets.

Endpoint

POST https://openapi.felo.ai/v2/x/tweet/replies

Request Body

Parameter	Type	Required	Description
`tweet_ids`	array of strings	Yes	Tweet ID(s) to get replies for
`cursor`	string	No	Pagination cursor
`since_time`	integer	No	Start time filter (Unix timestamp)
`until_time`	integer	No	End time filter (Unix timestamp)

Example

curl -X POST 'https://openapi.felo.ai/v2/x/tweet/replies' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "tweet_ids": ["1234567890"]
  }'

Success Response (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "results": [
      {
        "tweet_id": "1234567890",
        "total": 10,
        "has_next": true,
        "next_cursor": "cursor_jkl012",
        "replies": [
          {
            "id": "...",
            "content": "Great tweet!",
            "author": { "user_id": "...", "username": "..." },
            "created_at": "2026-03-09T12:30:00Z"
          }
        ]
      }
    ]
  }
}

Response Fields

Field	Type	Description
`results`	array	List of reply result objects
`results[].tweet_id`	string	Original tweet ID
`results[].total`	integer	Total number of replies
`results[].has_next`	boolean	Whether more replies are available
`results[].next_cursor`	string	Cursor for next page
`results[].replies`	array	List of reply tweet objects (see section 3)

Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	API Key is invalid or revoked
`X_SEARCH_FAILED`	400/500	X search request failed (check parameters or downstream error)
`RATE_LIMIT_EXCEEDED`	429	Too many requests, please retry after a short delay
`insufficient_credits`	402	Insufficient credits to complete the request

Credits & Rate Limiting

Credit Costs

Each API call deducts credits based on the number of results returned:

Endpoint	Credit Cost
`POST /x/user/info`	1 credit per user returned
`POST /x/user/search`	1 credit per user returned
`POST /x/user/tweets`	1 credit per tweet returned
`POST /x/tweet/search`	1 credit per tweet returned
`POST /x/tweet/replies`	1 credit per reply returned

Credits are deducted after the request completes, based on the actual number of results. If a request returns 0 results, no credits are deducted.

Minimum balance requirement: Your account must have at least 10 credits to make any X API request. Requests made with fewer than 10 credits will be rejected with HTTP 402.

Rate Limiting

Non-paid-subscriber accounts with a credit balance under 100 are subject to rate limiting:

Window	Limit
10 seconds	1 request
1 minute	3 requests
10 minutes	10 requests

Paid subscribers are exempt from rate limiting regardless of credit balance.

When rate limited, the API returns HTTP 429. The Retry-After header indicates the suggested wait time in seconds.