> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plugkit.co/llms.txt
> Use this file to discover all available pages before exploring further.

# X (Twitter)

> Post tweets with media and read account & tweet analytics.

X is a **publishing + analytics** integration via the X API v2 (OAuth 2.0 with
PKCE, auto-refreshing tokens).

<CardGroup cols={2}>
  <Card title="Publish" icon="feather">Text, images or video.</Card>
  <Card title="Analytics" icon="chart-simple">Account & per-tweet metrics.</Card>
</CardGroup>

## Connect

OAuth 2.0 (PKCE) flow:

```bash theme={null}
curl "https://api.plugkit.co/v1/connect/x?profileId=YOUR_PROFILE_ID" \
  -H "Authorization: Bearer sk_your_key"
```

Open the returned `authUrl` and approve. The callback `/connect/x/callback` must
be registered in your X app's **User authentication settings**.

## Publish a tweet

X accepts **text only**, **1–4 images**, **or** a single video/GIF (media is
optional):

```bash theme={null}
curl -X POST https://api.plugkit.co/v1/posts \
  -H "Authorization: Bearer sk_your_key" -H "Content-Type: application/json" \
  -d '{ "profileId": "PROFILE_ID", "accountIds": ["ACCOUNT_ID"],
        "content": "We just shipped 🚀", "mediaUrls": ["https://…/image.jpg"], "publishNow": true }'
```

The response includes the tweet's `platformPostId` and `platformPostUrl`.

## Analytics

Account-level metrics (the six the X API exposes):

```bash theme={null}
curl https://api.plugkit.co/v1/accounts/ACCOUNT_ID/x-analytics -H "Authorization: Bearer sk_your_key"
```

Per-tweet metrics (likes, retweets, replies, quotes, impressions, bookmarks) —
the tweet id is the number ending its URL, or the `platformPostId` from
publishing:

```bash theme={null}
curl https://api.plugkit.co/v1/accounts/ACCOUNT_ID/x-tweets/TWEET_ID -H "Authorization: Bearer sk_your_key"
```

<Note>
  Detailed impression/engagement data lives at the **tweet** level, not the
  account level — an X API limitation, not PlugKit's.
</Note>

## Not supported

X messaging (DMs) isn't exposed through this integration.

## Permissions

Scopes: `tweet.read`, `tweet.write`, `users.read`, `media.write`,
`offline.access` (for token refresh).