API resource

X (Twitter)

Search and read posts, and act as the account: repost, follow and bookmark. X bills every API call, so use these deliberately.

Search recent tweets

GET/v1/twitter/search

Works on: X

Search public tweets from the last 7 days matching an X search query, e.g. to discover tweets to reply to. The query string is passed through to X unchanged and supports X's search operators (`from:user`, `-is:retweet`, `is:reply`, `lang:en`, `"exact phrase"`, `conversation_id:123`, boolean `OR`, ...). Standalone operators like `is:` / `has:` / `lang:` must be combined with a keyword or `from:` clause. To reply to a found tweet, pass its `id` as the twitter platform entry's `platformSpecificData.replyToTweetId` when creating a post. Rate limit: 300 requests per 15-min window per connected account.

Query parameters

accountIdstringrequired

The account ID

querystringrequired

X search query, max 512 characters. Operators are passed through unchanged; X rejects malformed queries with a 400.

limitstring

Results per page. X requires a minimum of 10; values below 10 are rejected.

sinceIdstring

Only return tweets with an ID greater than (more recent than) this numeric tweet ID. Non-numeric values are rejected with 400.

untilIdstring

Only return tweets with an ID less than (older than) this numeric tweet ID. Non-numeric values are rejected with 400.

startTimestring

Oldest UTC timestamp (ISO 8601, inclusive), within the last 7 days

endTimestring

Newest UTC timestamp (ISO 8601, exclusive), within the last 7 days

cursorstring

Pagination cursor from a previous response

sortOrderstring

No description

curl "https://creatoros-production-5658.up.railway.app/v1/twitter/search?accountId=acc_Xt9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq4Z&query=%3Cquery%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "status": "success",
  "tweets": [
    {
      "id": "string",
      "text": "string",
      "created": "string",
      "conversationId": "string",
      "inReplyToTweetId": "string",
      "lang": "string",
      "author": {
        "id": "string",
        "username": "string",
        "displayName": "string",
        "avatar": "string",
        "verifiedType": "string"
      },
      "likeCount": 0,
      "replyCount": 0,
      "retweetCount": 0,
      "quoteCount": 0,
      "platform": "twitter"
    }
  ],
  "pagination": {
    "hasMore": true,
    "cursor": "string"
  },
  "meta": {
    "resultCount": 0,
    "newestId": "string",
    "oldestId": "string",
    "platform": "twitter"
  }
}

Look up a tweet

GET/v1/twitter/tweet

Works on: X

Resolve a single tweet by ID or URL into its text, author and public metrics. Use this to render a post you are referencing, e.g. the tweet quoted by a quote-style post. Unlike `/v1/twitter/search` this is not limited to the last 7 days and works for any tweet visible to the connected account. Billed as an X posts read ($0.005). Repeat lookups of the same tweet within the same UTC day are charged once.

Query parameters

accountIdstringrequired

The account ID whose X token is used for the lookup

tweetIdstringrequired

Numeric tweet ID or a tweet URL (e.g. https://x.com/user/status/123...). The same name the other /v1/twitter operations use (retweet, bookmark).

idstring

Alias of tweetId, kept for existing callers

curl "https://creatoros-production-5658.up.railway.app/v1/twitter/tweet?accountId=acc_Xt9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq4Z&tweetId=%3CtweetId%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "status": "success",
  "tweet": {
    "id": "string",
    "text": "string",
    "created": "string",
    "conversationId": "string",
    "inReplyToTweetId": "string",
    "lang": "string",
    "author": {
      "id": "string",
      "username": "string",
      "displayName": "string",
      "avatar": "string",
      "verifiedType": "string"
    },
    "likeCount": 0,
    "replyCount": 0,
    "retweetCount": 0,
    "quoteCount": 0,
    "platform": "twitter"
  }
}

Retweet a post

POST/v1/twitter/retweet

Works on: X

Retweet (repost) a tweet by ID. Rate limit: 50 requests per 15-min window. Shares the 300/3hr creation limit with tweet creation.

Body

accountIdstringrequired

The account ID

tweetIdstringrequired

The ID of the tweet to retweet

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/twitter/retweet" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Xt9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq4Z",
    "tweetId": "<tweetId>"
  }'

Response 200

{
  "status": "success",
  "tweetId": "string",
  "retweeted": true,
  "platform": "twitter"
}

Undo retweet

DELETE/v1/twitter/retweet

Works on: X

Undo a retweet (un-repost a tweet).

Query parameters

accountIdstringrequired

No description

tweetIdstringrequired

The ID of the original tweet to un-retweet

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/twitter/retweet?accountId=acc_Xt9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq4Z&tweetId=%3CtweetId%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "status": "success",
  "tweetId": "string",
  "retweeted": false,
  "platform": "twitter"
}

Follow a user

POST/v1/twitter/follow

Works on: X

Follow a user on X. Requires the follows.write OAuth scope. For protected accounts, a follow request is sent instead (pending_follow will be true).

Body

accountIdstringrequired

The account ID

targetUserIdstringrequired

The X ID of the user to follow

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/twitter/follow" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Xt9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq4Z",
    "targetUserId": "<targetUserId>"
  }'

Response 200

{
  "status": "success",
  "targetUserId": "string",
  "following": true,
  "pending_follow": true,
  "platform": "twitter"
}

Unfollow a user

DELETE/v1/twitter/follow

Works on: X

Unfollow a user on X.

Query parameters

accountIdstringrequired

No description

targetUserIdstringrequired

The X ID of the user to unfollow

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/twitter/follow?accountId=acc_Xt9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq4Z&targetUserId=%3CtargetUserId%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "status": "success",
  "targetUserId": "string",
  "following": false,
  "platform": "twitter"
}

Bookmark a tweet

POST/v1/twitter/bookmark

Works on: X

Bookmark a tweet by ID. Requires the bookmark.write OAuth scope. Rate limit: 50 requests per 15-min window.

Body

accountIdstringrequired

The account ID

tweetIdstringrequired

The ID of the tweet to bookmark

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/twitter/bookmark" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Xt9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq4Z",
    "tweetId": "<tweetId>"
  }'

Response 200

{
  "status": "success",
  "tweetId": "string",
  "bookmarked": true,
  "platform": "twitter"
}

Remove bookmark

DELETE/v1/twitter/bookmark

Works on: X

Remove a bookmark from a tweet.

Query parameters

accountIdstringrequired

No description

tweetIdstringrequired

The ID of the tweet to unbookmark

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/twitter/bookmark?accountId=acc_Xt9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq4Z&tweetId=%3CtweetId%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "status": "success",
  "tweetId": "string",
  "bookmarked": false,
  "platform": "twitter"
}

PreviousFacebook NextPosting queue