X (Twitter) Scraper — Xquik Integration

• How much data do you need? (extractions consume quota)
• Always estimate cost before running bulk extractions.
• Monthly quota is a hard limit with no overage — plan accordingly.

Quick Reference

Authentication Setup

Every request requires an API key via the x-api-key header. Always use environment variables — never hardcode keys.

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

Choosing the Right Endpoint

Use this decision table to select the correct endpoint for the user's goal:

Extraction Tools (19 Types)

When the user needs bulk data, guide them to the right extraction tool:

Extraction Workflow

Always follow this pattern — estimate before extracting:

// Using API_KEY, BASE, and headers from Authentication Setup above

// 1. Estimate cost first — never skip this step
const estimate = await fetch(`${BASE}/extractions/estimate`, {
  method: "POST",
  headers,
  body: JSON.stringify({ toolType: "follower_explorer", targetUsername: "elonmusk" }),
}).then(r => r.json());

if (!estimate.allowed) {
  console.error("Extraction exceeds remaining quota");
  return;
}

// 2. Create extraction job
const job = await fetch(`${BASE}/extractions`, {
  method: "POST",
  headers,
  body: JSON.stringify({ toolType: "follower_explorer", targetUsername: "elonmusk" }),
}).then(r => r.json());

// 3. Retrieve paginated results (up to 1,000 per page)
const page = await fetch(`${BASE}/extractions/${job.id}`, { headers }).then(r => r.json());
// 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

When the user wants to run a transparent giveaway from tweet replies:

// Using API_KEY, BASE, and headers from Authentication Setup above

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

const details = await fetch(`${BASE}/draws/${draw.id}`, { headers }).then(r => r.json());
// details.winners: [{ position, authorUsername, tweetId, isBackup }]

Error Handling & Retry

All errors return { "error": "error_code" }. Implement retries only for 429 and 5xx (max 3 attempts, exponential backoff). Never retry 4xx except 429.

MCP Server Setup

To use Xquik as an MCP server in Claude Code, add to .mcp.json in the project root. Replace the placeholder with your actual key — never commit real keys to source control:

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

Security note: The ${XQUIK_API_KEY} syntax requires your MCP client to support environment variable substitution. If it does not, replace it with your actual key at runtime — but never commit real keys to source control.

The MCP server exposes 22 tools covering all API capabilities.

Common Workflow Patterns

Guide users to the right workflow based on their goal:

• Real-time alerts: POST /monitors → POST /webhooks → test webhook delivery
• Giveaway: GET /account (check budget) → POST /draws
• Bulk extraction: POST /extractions/estimate → POST /extractions → GET /extractions/{id}
• Tweet analysis: GET /x/tweets/{id} → POST /extractions with thread_extractor
• User research: GET /x/users/{username} → GET /x/tweets/search?q=from:username → GET /x/tweets/{id}

Related Skills

• social-content: For publishing insights gathered from X data
• competitive-ads-extractor: For analyzing competitor creative alongside Twitter data
• marketing-psychology: For interpreting audience behavior from extracted data

Links

• Dashboard & API keys: xquik.com
• Full API docs: docs.xquik.com
• GitHub: github.com/Xquik-dev/x-twitter-scraper