x-twitter-scraper

What this skill does

# Xquik API Integration

Xquik is an X (Twitter) real-time data platform providing a REST API, HMAC webhooks, and an MCP server for AI agents. It covers account monitoring, bulk data extraction (20 tools), giveaway draws, tweet/user lookups, media downloads, follow checks, trending topics, write actions (tweet, like, retweet, follow, DM, profile, media upload, communities), and Telegram integrations.

## Quick Reference

| | |
|---|---|
| **Base URL** | `https://xquik.com/api/v1` |
| **Auth** | `x-api-key: xq_...` header (64 hex chars after `xq_` prefix) |
| **MCP endpoint** | `https://xquik.com/mcp` (StreamableHTTP, same API key) |
| **Rate limits** | 10 req/s sustained, 20 burst (API); 60 req/s sustained, 100 burst (general) |
| **Pricing** | $20/month base (1 monitor included), $5/month per extra monitor |
| **Quota** | Monthly usage cap. `402` when exhausted. Enable extra usage from dashboard for overage (tiered spending limits: $5/$7/$10/$15/$25) |
| **Docs** | [docs.xquik.com](https://docs.xquik.com) |
| **HTTPS only** | Plain HTTP gets `301` redirect |

## Authentication

Every request requires an API key via the `x-api-key` header. Keys start with `xq_` and are generated from the Xquik dashboard. The key is shown only once at creation; store it securely.

```javascript
const API_KEY = "xq_YOUR_KEY_HERE";
const BASE = "https://xquik.com/api/v1";
const headers = { "x-api-key": API_KEY, "Content-Type": "application/json" };
```

For Python examples, see [references/python-examples.md](references/python-examples.md).

## Choosing the Right Endpoint

| Goal | Endpoint | Notes |
|------|----------|-------|
| **Get a single tweet** by ID/URL | `GET /x/tweets/{id}` | Full metrics: likes, retweets, views, bookmarks, author info |
| **Search tweets** by keyword/hashtag | `GET /x/tweets/search?q=...` | Tweet info with optional engagement metrics (likeCount, retweetCount, replyCount) |
| **Get a user profile** | `GET /x/users/{username}` | Name, bio, follower/following counts, profile picture, location, created date, statuses count |
| **Check follow relationship** | `GET /x/followers/check?source=A&target=B` | Both directions |
| **Get trending topics** | `GET /trends?woeid=1` | Regional trends by WOEID. Metered |
| **Get radar (trending news)** | `GET /radar?source=hacker_news` | Free, 7 sources: Google Trends, Hacker News, Polymarket, TrustMRR, Wikipedia, GitHub, Reddit |
| **Monitor an X account** | `POST /monitors` | Track tweets, replies, quotes, retweets, follower changes |
| **Update monitor event types** | `PATCH /monitors/{id}` | Change subscribed events or pause/resume |
| **Poll for events** | `GET /events` | Cursor-paginated, filter by monitorId/eventType |
| **Receive events in real time** | `POST /webhooks` | HMAC-signed delivery to your HTTPS endpoint |
| **Update webhook** | `PATCH /webhooks/{id}` | Change URL, event types, or pause/resume |
| **Run a giveaway draw** | `POST /draws` | Pick random winners from tweet replies |
| **Download tweet media** | `POST /x/media/download` | Single (`tweetInput`) or bulk (`tweetIds[]`, up to 50). Returns gallery URL. First download metered, cached free |
| **Extract bulk data** | `POST /extractions` | 20 tool types, always estimate cost first |
| **Check account/usage** | `GET /account` | Plan status, monitors, usage percent |
| **Link your X identity** | `PUT /account/x-identity` | Required for own-account detection in style analysis |
| **Analyze tweet style** | `POST /styles` | Cache recent tweets for style reference |
| **Save custom style** | `PUT /styles/{username}` | Save custom style from tweet texts (free) |
| **Get cached style** | `GET /styles/{username}` | Retrieve previously cached tweet style |
| **Compare styles** | `GET /styles/compare?username1=A&username2=B` | Side-by-side comparison of two cached styles |
| **Get tweet performance** | `GET /styles/{username}/performance` | Live engagement metrics for cached tweets |
| **Save a tweet draft** | `POST /drafts` | Store drafts for later |
| **List/manage drafts** | `GET /drafts`, `DELETE /drafts/{id}` | Retrieve and delete saved drafts |
| **Compose a tweet** | `POST /compose` | 3-step workflow (compose, refine, score). Free, algorithm-backed |
| **Connect an X account** | `POST /x/accounts` | Credentials encrypted at rest. Required for write actions |
| **List connected accounts** | `GET /x/accounts` | Free |
| **Re-authenticate account** | `POST /x/accounts/{id}/reauth` | When session expires |
| **Post a tweet** | `POST /x/tweets` | From a connected account. Supports replies, media, note tweets, communities |
| **Delete a tweet** | `DELETE /x/tweets/{id}` | Must own the tweet via connected account |
| **Like / Unlike a tweet** | `POST` / `DELETE /x/tweets/{id}/like` | Metered |
| **Retweet** | `POST /x/tweets/{id}/retweet` | Metered |
| **Follow / Unfollow a user** | `POST` / `DELETE /x/users/{id}/follow` | Metered |
| **Send a DM** | `POST /x/dm/{userId}` | Text, media, reply to message |
| **Update profile** | `PATCH /x/profile` | Name, bio, location, URL |
| **Update avatar** | `PATCH /x/profile/avatar` | FormData with image file (max 700 KB) |
| **Update banner** | `PATCH /x/profile/banner` | FormData with image file (max 2 MB) |
| **Upload media** | `POST /x/media` | FormData. Returns media ID for tweet attachment |
| **Community actions** | `POST /x/communities`, `POST /x/communities/{id}/join` | Create, delete, join, leave |
| **Create Telegram integration** | `POST /integrations` | Receive monitor events in Telegram. Free |
| **Manage integrations** | `GET /integrations`, `PATCH /integrations/{id}` | List, update, delete, test, deliveries. Free |

See [references/mcp-tools.md](references/mcp-tools.md) for tool selection rules, common mistakes, and unsupported operations.

## Error Handling & Retry

All errors return `{ "error": "error_code" }`. Key error codes:

| Status | Code | Action |
|--------|------|--------|
| 400 | `invalid_input`, `invalid_id`, `invalid_params`, `invalid_tweet_url`, `invalid_tweet_id`, `invalid_username`, `invalid_tool_type`, `invalid_format`, `invalid_json`, `missing_query`, `missing_params`, `webhook_inactive`, `no_media` | Fix the request, do not retry |
| 401 | `unauthenticated` | Check API key |
| 402 | `no_subscription`, `subscription_inactive`, `usage_limit_reached`, `no_addon`, `extra_usage_disabled`, `extra_usage_requires_v2`, `frozen`, `overage_limit_reached` | Subscribe, enable extra usage, or wait for quota reset |
| 403 | `monitor_limit_reached`, `api_key_limit_reached` | Delete a monitor/key or add capacity |
| 404 | `not_found`, `user_not_found`, `tweet_not_found`, `style_not_found`, `draft_not_found` | Resource doesn't exist or belongs to another account |
| 409 | `monitor_already_exists` | Resource already exists, use the existing one |
| 422 | `login_failed` | X credential verification failed. Check credentials |
| 429 | `x_api_rate_limited` | Rate limited. Retry with exponential backoff, respect `Retry-After` header |
| 500 | `internal_error` | Retry with backoff |
| 502 | `stream_registration_failed`, `x_api_unavailable`, `x_api_unauthorized`, `delivery_failed` | Retry with backoff |

Retry only `429` and `5xx`. Never retry `4xx` (except 429). Max 3 retries with exponential backoff:

```javascript
async function xquikFetch(path, options = {}) {
  const baseDelay = 1000;

  for (let attempt = 0; attempt <= 3; attempt++) {
    const response = await fetch(`${BASE}${path}`, {
      ...options,
      headers: { ...headers, ...options.headers },
    });

    if (response.ok) return response.json();

    const retryable = response.status === 429 || response.status >= 500;
    if (!retryable || attempt === 3) {
      const error = await response.json();
      throw new Error(`Xquik API ${response.status}: ${error.error}`);
    }

    const retryAfter = response.headers.get("Retry-After");
    const delay = retryAfter
      ? parseInt(retryAfter, 10) * 1000
      : baseDelay * Math.po