AGENT SKILL

x-twitter-scraper

Use when the user wants to integrate with the X (Twitter) API via Xquik to search tweets, look up user profiles, extract followers, run giveaway draws, monitor accounts, or access trending topics. Also use when the user mentions 'Xquik,' 'Twitter API,' 'X API,' 'tweet scraper,' 'follower extraction,' or 'Twitter monitoring.' Covers REST API, webhooks, and MCP server setup.

License 许可
MIT
最近更新
2026-09-12
Stars
★ 2
Forks
0

01 前言 Front Matter

name
x-twitter-scraper
description
Use when the user wants to integrate with the X (Twitter) API via Xquik to search tweets, look up user profiles, extract followers, run giveaway draws, monitor accounts, or access trending topics. Also use when the user mentions 'Xquik,' 'Twitter API,' 'X API,' 'tweet scraper,' 'follower extraction,' or 'Twitter monitoring.' Covers REST API, webhooks, and MCP server setup.

03 SKILL.md 正文

X (Twitter) Scraper — Xquik Integration

You are an expert X (Twitter) data integration specialist. You help users build applications that interact with the X platform through the Xquik API, covering tweet search, user lookups, follower extraction, account monitoring, giveaway draws, and real-time event webhooks.

Before Writing Code

Gather this context (ask if not provided):

1. Goal

  • What data do you need from X? (tweets, users, followers, trending topics)
  • Is this a one-time extraction or ongoing monitoring?
  • Do you need real-time events or periodic polling?

2. Authentication

  • Do you have an Xquik API key? If not, guide them to xquik.com to create one.
  • Remind them: keys start with xq_ and are shown only once at creation — store securely in environment variables.

3. Scale & Budget

  • 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

Base URL https://xquik.com/api/v1
Auth x-api-key header (key starts with xq_, 64 hex chars)
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 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:

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)

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

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

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.

Status Meaning Action
400 Invalid input Fix the request parameters
401 Bad API key Verify XQUIK_API_KEY env var is set correctly
402 No subscription or quota exhausted Check account status, upgrade plan if needed
404 Resource not found Verify the ID/username exists
429 Rate limited Respect Retry-After header, back off

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

04 同仓库更多 Skills

Carchaloneo22
Carchaloneo22/Claude-Code-template

zapier-make-patterns

No-code automation democratizes workflow building. Zapier and Make (formerly Integromat) let non-developers automate business processes without writing code. But no-code doesn't mean no-complexity - these platforms have their own patterns, pitfalls, and breaking points. This skill covers when to use which platform, how to build reliable automations, and when to graduate to code-based solutions. Key insight: Zapier optimizes for simplicity and integrations (7000+ apps), Make optimizes for power

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

yeet

Use only when the user explicitly asks to stage, commit, push, and open a GitHub pull request in one flow using the GitHub CLI (`gh`).

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

workflow-automation

Workflow automation is the infrastructure that makes AI agents reliable. Without durable execution, a network hiccup during a 10-step payment flow means lost money and angry customers. With it, workflows resume exactly where they left off. This skill covers the platforms (n8n, Temporal, Inngest) and patterns (sequential, parallel, orchestrator-worker) that turn brittle scripts into production-grade automation. Key insight: The platforms make different tradeoffs. n8n optimizes for accessibility

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

trigger-dev

Trigger.dev expert for background jobs, AI workflows, and reliable async execution with excellent developer experience and TypeScript-first design. Use when: trigger.dev, trigger dev, background task, ai background job, long running task.

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

planning-with-files

Transforms workflow to use Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Use when starting complex tasks, multi-step projects, research tasks, or when the user mentions planning, organizing work, tracking progress, or wants structured output.

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

n8n-workflow-patterns

Proven workflow architectural patterns from real n8n workflows. Use when building new workflows, designing workflow structure, choosing workflow patterns, planning workflow architecture, or asking about webhook processing, HTTP API integration, database operations, AI agent workflows, or scheduled tasks.

★ 2