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

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.

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

// 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:

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:

{
  "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

x-twitter-scraper