x-twitter-scraper

# 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 (19 tools), giveaway draws, tweet/user lookups, follow checks, and trending topics.

## 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, hard limit, no overage. `402` when exhausted. |
| **Docs** | [docs.xquik.com](https://docs.xquik.com) |

## Authentication

Every request requires an API key via the `x-api-key` header. Keys start with `xq_` and are generated from the [Xquik dashboard](https://xquik.com). 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" };
```

## Choosing the Right Endpoint

| Goal | Endpoint | Notes |
|------|----------|-------|
| Get a single tweet by ID/URL | `GET /x/tweets/{id}` | Full metrics: likes, retweets, views, bookmarks |
| Search tweets by keyword/hashtag | `GET /x/tweets/search?q=...` | Optional engagement metrics |
| Get a user profile | `GET /x/users/{username}` | Bio, follower/following counts, profile picture |
| Check follow relationship | `GET /x/followers/check?source=A&target=B` | Both directions |
| Get trending topics | `GET /trends?woeid=1` | Free, no quota consumed |
| Monitor an X account | `POST /monitors` | Track tweets, replies, quotes, follower changes |
| 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 |
| Run a giveaway draw | `POST /draws` | Pick random winners from tweet replies |
| Extract bulk data | `POST /extractions` | 19 tool types, always estimate cost first |
| Check account/usage | `GET /account` | Plan status, monitors, usage percent |

## Extraction Tools (19 Types)

| Tool Type | Required Field | Description |
|-----------|---------------|-------------|
| `reply_extractor` | `targetTweetId` | Users who replied to a tweet |
| `repost_extractor` | `targetTweetId` | Users who retweeted a tweet |
| `quote_extractor` | `targetTweetId` | Users who quote-tweeted a tweet |
| `thread_extractor` | `targetTweetId` | All tweets in a thread |
| `article_extractor` | `targetTweetId` | Article content linked in a tweet |
| `follower_explorer` | `targetUsername` | Followers of an account |
| `following_explorer` | `targetUsername` | Accounts followed by a user |
| `verified_follower_explorer` | `targetUsername` | Verified followers of an account |
| `mention_extractor` | `targetUsername` | Tweets mentioning an account |
| `post_extractor` | `targetUsername` | Posts from an account |
| `community_extractor` | `targetCommunityId` | Members of a community |
| `community_moderator_explorer` | `targetCommunityId` | Moderators of a community |
| `community_post_extractor` | `targetCommunityId` | Posts from a community |
| `community_search` | `targetCommunityId` + `searchQuery` | Search posts within a community |
| `list_member_extractor` | `targetListId` | Members of a list |
| `list_post_extractor` | `targetListId` | Posts from a list |
| `list_follower_explorer` | `targetListId` | Followers of a list |
| `space_explorer` | `targetSpaceId` | Participants of a Space |
| `people_search` | `searchQuery` | Search for users by keyword |

### Extraction Workflow

```javascript
// 1. Estimate cost
const estimate = await xquikFetch("/extractions/estimate", {
  method: "POST",
  body: JSON.stringify({ toolType: "follower_explorer", targetUsername: "elonmusk" }),
});

if (!estimate.allowed) return;

// 2. Create extraction job
const job = await xquikFetch("/extractions", {
  method: "POST",
  body: JSON.stringify({ toolType: "follower_explorer", targetUsername: "elonmusk" }),
});

// 3. Retrieve paginated results (up to 1,000 per page)
const page = await xquikFetch(`/extractions/${job.id}`);
// page.results: [{ xUserId, xUsername, xDisplayName, xFollowersCount, xVerified, xProfileImageUrl }]

// 4. Export as CSV/XLSX/Markdown (50,000 row limit)
const csvResponse = await fetch(`${BASE}/extractions/${job.id}/export?format=csv`, { headers });
```

## Giveaway Draws

Run transparent giveaway draws from tweet replies with configurable filters:

```javascript
const draw = await xquikFetch("/draws", {
  method: "POST",
  body: JSON.stringify({
    tweetUrl: "https://x.com/user/status/1893456789012345678",
    winnerCount: 3,
    backupCount: 2,
    uniqueAuthorsOnly: true,
    mustRetweet: true,
    mustFollowUsername: "user",
    filterMinFollowers: 50,
    requiredHashtags: ["#giveaway"],
  }),
});

const details = await xquikFetch(`/draws/${draw.id}`);
// details.winners: [{ position, authorUsername, tweetId, isBackup }]
```

## Error Handling & Retry

All errors return `{ "error": "error_code" }`. Retry only `429` and `5xx` (max 3 attempts, exponential backoff). Never retry `4xx` except 429. Key codes:

| Status | Meaning |
|--------|---------|
| 400 | Invalid input -- fix the request |
| 401 | Bad API key |
| 402 | No subscription or quota exhausted |
| 404 | Resource not found |
| 429 | Rate limited -- respect `Retry-After` header |

## MCP Server Setup (Claude Code)

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "xquik": {
      "type": "streamable-http",
      "url": "https://xquik.com/mcp",
      "headers": {
        "x-api-key": "xq_YOUR_KEY_HERE"
      }
    }
  }
}
```

The MCP server exposes 22 tools covering all API capabilities. Supported platforms: Claude Code, Claude Desktop, ChatGPT, Codex CLI, Cursor, VS Code, Windsurf, OpenCode.

## Workflow Patterns

- **Real-time alerts:** `add-monitor` -> `add-webhook` -> `test-webhook`
- **Giveaway:** `get-account` (check budget) -> `run-draw`
- **Bulk extraction:** `estimate-extraction` -> `run-extraction` -> `get-extraction`
- **Tweet analysis:** `lookup-tweet` -> `run-extraction` with `thread_extractor`
- **User research:** `get-user-info` -> `search-tweets from:username` -> `lookup-tweet`

## Links

- **Dashboard & API keys**: [xquik.com](https://xquik.com)
- **Full API docs**: [docs.xquik.com](https://docs.xquik.com)
- **GitHub (skill source)**: [github.com/Xquik-dev/x-twitter-scraper](https://github.com/Xquik-dev/x-twitter-scraper)