The X (Twitter) API for mentions, replies, and DMs

Mentions, replies, and DMs on X through one API.

Start for free Read the docs

Free tier, no credit card
Instant API key
MCP server included

On X (Twitter)

Post

Ledge Skate & Shoe

@ledgeskate

New white lows just landed. In store Saturday, all sizes.

2:00 PMOct 6, 2026

Maya R.@maya_r2h

Do these come in black?

Ledge Skate & Shoe@ledgeskate1m

Yes, black with a gum sole, sizes 36 to 46.

Jin K.@jin_k5h

Skated mine all weekend, the grip is unreal.

POST/v1/inbox/comments/{postId}200 OK

Capabilities: What you can build on X (Twitter)

Every capability is one endpoint, the same one you call on every other platform.The screens show where each call lands.

Direct Messages
Read DM conversations and send messages through the same unified inbox you use for Instagram and Facebook messaging.
- GET/v1/inbox/conversations
- POST/v1/inbox/conversations/{id}/messages
Tom B.
Tom B.
@tom_b
Friday
Ordered the canvas highs, size 44.
Thanks Tom, it ships today.
Today
This was at my door, but it's not my order.
❤️
Tom B.This was at my door, but it's not my order.
Sorry Tom, a mix-up. Yours is at your front desk.
9:14 AMSeen
Found itStill missing
Publishing
Text tweets with up to 4 images, or one video, or one animated GIF, uploaded for you through X's chunked media upload.
- POST/v1/posts
Post
Ledge Skate & Shoe
@ledgeskate
New white lows just landed. In store Saturday, all sizes.
2:00 PMOct 6, 20263.4K Views
Comments
Read replies on your tweets, reply back, and hide or delete your own replies. Liking a reply is not available; X removed like and unlike writes from self-serve API tiers.
- GET/v1/inbox/comments/{postId}
- POST/v1/inbox/comments/{postId}
- read
- reply
- hide
- delete
Mentions
Fetch tweets mentioning your authenticated account through a dedicated endpoint, scoped to that account.
- GET/v1/accounts/{id}/mentions
- tweets mentioning you

On every platform

Agent-ready
Every X (Twitter) capability is a typed tool on the SocialAPI.ai MCP server.
- social_api_list_post_comments
- social_api_send_dm
- social_api_validate_post
One API key
The key that calls X (Twitter) calls all 13 platforms.
Authorization: Bearer sapi_key_…
Predictable errors
The same status codes everywhere, whatever the platform behind them.
- 401expired token
- 429rate limited
- 501not on this platform

Call the X (Twitter) API

List mentions of your X account

Pull every tweet mentioning your account through the same GET /v1/accounts/{id}/mentions endpoint used for Instagram and Facebook mentions.

curl "https://api.social-api.ai/v1/accounts/<x-account-id>/mentions?limit=10" \
  -H "Authorization: Bearer <your-api-key>" | jq

# Response
{
  "data": [
    {
      "id": "sapi_mnt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U",
      "type": "mention",
      "author": { "username": "someuser", "name": "Some User" },
      "content": { "text": "@yourhandle just tried your API, love it" },
      "received_at": "2026-03-20T18:00:00Z"
    }
  ],
  "next_cursor": "..."
}

import requests

resp = requests.get(
    "https://api.social-api.ai/v1/accounts/<x-account-id>/mentions",
    headers={"Authorization": "Bearer <your-api-key>"},
    params={"limit": 10},
)
for mention in resp.json()["data"]:
    print(mention["author"]["username"], mention["content"]["text"])

const res = await fetch(
  "https://api.social-api.ai/v1/accounts/<x-account-id>/mentions?limit=10",
  { headers: { Authorization: "Bearer <your-api-key>" } }
);
const { data } = await res.json();
for (const mention of data) {
  console.log(mention.author.username, mention.content.text);
}

Comparison: The official API vs one API key

Aspect	The X API v2 (raw)	With SocialAPI.ai
Rate limits	The X API v2 (raw)Per-app buckets you track yourself across every endpoint tier.	With SocialAPI.aiYour own app's bucket, never shared with other customers. Platform throttling surfaces as a clear 429 that does not touch your SocialAPI.ai quota.
Data shape	The X API v2 (raw)Tweet objects with expansions, includes arrays, and pagination tokens to stitch together.	With SocialAPI.aiOne normalized schema for mentions, replies, and DMs, identical to every other platform.
OAuth setup	The X API v2 (raw)OAuth 2.0 with PKCE, token refresh, and scope management in your own code.	With SocialAPI.aiPaste your app's Client ID and Secret once; account connection and token refresh are handled.
Multi-platform	The X API v2 (raw)An X-only integration you maintain separately from Meta, Google, and the rest.	With SocialAPI.aiThe same /v1/inbox and /v1/posts endpoints cover X and the other 12 platforms, as far as each one allows.

In depth: How the X (Twitter) API works on SocialAPI.ai

Get every tweet that mentions you, manage the replies under your posts, and read and send DMs through the same unified API you use for every other platform. You bring your own X developer app (a ten-minute setup), which means your own rate-limit bucket instead of a shared one.

Mention tracking

Fetch every tweet mentioning your authenticated account through a dedicated endpoint, scoped to that account rather than your whole workspace. Poll it on a schedule to build brand monitoring, a support queue, or an automated triage workflow, the same way you would for Instagram or Facebook mentions.

Reply and thread management

Read the replies under your tweets, post a reply back, and hide or delete your own replies through the same comment endpoints used across every other platform. Liking a reply is not available: X removed like and unlike writes from its self-serve API tiers and reserved them for Enterprise.

Direct messages

List DM conversations, read message history, and send replies through the unified inbox endpoint, the same request and response shape you already use for Instagram and Facebook messaging. An X integration does not need its own code path.

Your own rate-limit bucket

X scopes API access per developer app, so every customer routed through one shared app would compete for the same quota. Bring your own X developer app, about ten minutes to set up, and your calls draw from a bucket only you use.

One schema, same as every other platform

Mentions, replies, and DMs on X come back in the same normalized schema used by Instagram, Facebook, LinkedIn, and every other connected platform. Build your inbox logic once and it works whether the event came from X or anywhere else.

Simple, honest pricing.

Reading comments, DMs, and mentions is free and unlimited on every plan. Paid plans start at $29/mo with unlimited posts and interactions. The free tier needs no credit card.

Start free Social media API pricing

Frequently asked questions

What developers ask before they ship X (Twitter).

Does X (Twitter) have a free API?

X's own API free tier is write-only: it lets you post but not read tweets, replies, mentions, or DMs, so a free X developer app cannot power a read-heavy integration on its own. X now prices paid access on usage rather than a flat monthly subscription, so cost scales with call volume. SocialAPI.ai's own plans start free and include X, but your X developer app still needs a paid X tier to read mentions and replies.

How do I get mentions from the X API?

Call GET /v1/accounts/{account_id}/mentions with your SocialAPI.ai API key and the ID of your connected X account. It returns tweets mentioning that account, newest first, in the same format used for mentions on Instagram and Facebook.

Can I send DMs through the X API?

Yes. List conversations and send messages through the same /v1/inbox/conversations endpoints used for Instagram and Facebook DMs. Your X developer app needs the dm.read and dm.write scopes enabled.

Why do I need my own X developer app?

X scopes rate limits per developer app, so every SocialAPI.ai customer sharing one app would compete for the same quota. Bringing your own app, about ten minutes to register and connect, gives you an independent rate-limit bucket aligned with whatever X access tier you are on.

Can I post tweets with images or video?

Yes. Attach up to 4 images, or one video, or one animated GIF, and SocialAPI.ai uploads them through X's chunked media upload before posting. If an upload fails the whole post fails, so a tweet never goes out without the media you asked for. Accounts connected before 2026-07-27 need to reconnect once to grant the media.write scope.

Can AI agents read my X mentions?

Yes. The built-in MCP server exposes inbox reads, including mentions, as tools, so Claude and other MCP-capable agents can pull your X mentions and draft replies inside your existing approval flow.

Every other platform, one API: Every other platform, one API

Same key, same shapes, same webhook.

Ready to unify your social interactions?

Free tier available. No credit card required. Ships with the MCP server.