x-developer 2.6.7 → 2.7.1

package/skills/x-twitter-scraper/references/python-examples.md

@@ -1,201 +0,0 @@
-# Xquik Python examples
-
-Use these Python examples for authentication, retries, extractions, draws, and webhooks.
-
-## Authentication
-
-> These examples send credentials, parameters, and
-> returned data to and from `xquik.com`. Keep the key in a secret store. Get
-> explicit approval before private reads, writes, exports, persistent resources,
-> webhooks, or metered jobs. Never forward private results without separate
-> approval.
-
-```python
-import json
-import urllib.error
-import urllib.request
-
-def load_secret(name: str) -> str:
-    """Read from the runtime secret store."""
-    raise RuntimeError(f"Configure {name} in your secret store.")
-
-API_KEY = load_secret("XQUIK_API_KEY")
-BASE = "https://xquik.com/api/v1"
-HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}
-```
-
-## Retry with exponential backoff
-
-```python
-import time, random
-
-def xquik_fetch(path, method="GET", json_body=None, max_retries=3):
-    base_delay = 1.0
-    method = method.upper()
-    retry_safe = method in {"GET", "HEAD", "OPTIONS"}
-
-    for attempt in range(max_retries + 1):
-        retry_after = None
-        body = json.dumps(json_body).encode() if json_body is not None else None
-        request = urllib.request.Request(
-            f"{BASE}{path}", data=body, headers=HEADERS, method=method
-        )
-
-        try:
-            with urllib.request.urlopen(request, timeout=30) as response:
-                return json.loads(response.read())
-        except urllib.error.HTTPError as error:
-            status = error.code
-            payload = json.loads(error.read() or b"{}")
-            retry_after = error.headers.get("Retry-After")
-
-        retryable = retry_safe and (status == 429 or status >= 500)
-        if not retryable or attempt == max_retries:
-            raise Exception(f"Xquik API {status}: {payload.get('error', 'request failed')}")
-
-        delay = int(retry_after) if retry_after else base_delay * (2 ** attempt) + random.uniform(0, 1)
-        time.sleep(delay)
-```
-
-## Extraction workflow
-
-```python
-RESULTS_LIMIT = 1000
-
-def require_explicit_approval(scope: str) -> None:
-    raise RuntimeError(
-        f"Approval required for {scope}. Implement the approval gate first."
-    )
-
-# Estimate the extraction.
-estimate = xquik_fetch("/extractions/estimate", method="POST", json_body={
-    "toolType": "reply_extractor",
-    "targetTweetId": "1893704267862470862",
-    "resultsLimit": RESULTS_LIMIT,
-})
-
-if not estimate["allowed"]:
-    print(f"Extraction estimate: {estimate['creditsRequired']} credits. Balance: {estimate['creditsAvailable']}.")
-    exit()
-
-# Create the bounded job only after approval.
-require_explicit_approval(
-    "the bounded extraction job, usage, recipients, and retention"
-)
-job = xquik_fetch("/extractions", method="POST", json_body={
-    "toolType": "reply_extractor",
-    "targetTweetId": "1893704267862470862",
-    "resultsLimit": RESULTS_LIMIT,
-})
-
-# Poll until the job finishes. Large jobs may remain in "running" state.
-while job["status"] in ("pending", "running"):
-    time.sleep(2)
-    job = xquik_fetch(f"/extractions/{job['id']}")
-
-# Get every approved result page.
-cursor = None
-results = []
-
-while True:
-    path = f"/extractions/{job['id']}"
-    if cursor:
-        path += f"?cursor={cursor}"
-    page = xquik_fetch(path)
-    results.extend(page["results"])
-
-    if not page["hasMore"]:
-        break
-    cursor = page["nextCursor"]
-
-print(f"Extracted {len(results)} results")
-```
-
-## Giveaway draw
-
-```python
-# Create a draw with explicit filters.
-draw = xquik_fetch("/draws", method="POST", json_body={
-    "tweetUrl": "https://x.com/burakbayir/status/1893456789012345678",
-    "winnerCount": 3,
-    "backupCount": 2,
-    "uniqueAuthorsOnly": True,
-    "mustRetweet": True,
-    "mustFollowUsername": "burakbayir",
-    "filterMinFollowers": 50,
-    "filterAccountAgeDays": 30,
-    "requiredKeywords": ["giveaway"],
-})
-
-# Get the winners.
-details = xquik_fetch(f"/draws/{draw['id']}")
-for winner in details["winners"]:
-    role = "Backup" if winner["isBackup"] else "Winner"
-    print(f"{role} #{winner['position']}: @{winner['authorUsername']}")
-```
-
-## Python standard library webhook handler
-
-```python
-import hashlib
-import hmac
-import json
-import re
-import time
-from http.server import BaseHTTPRequestHandler, HTTPServer
-
-def load_secret(name: str) -> str:
-    """Read from your runtime secret store."""
-    raise RuntimeError(f"Configure {name} in your secret store.")
-
-# Use the per-webhook secret from POST /webhooks, not an Xquik account credential.
-WEBHOOK_SECRET = load_secret("XQUIK_WEBHOOK_SECRET")
-processed_delivery_ids = set()  # Use durable storage in deployed services.
-
-def verify_signature(payload: bytes, signature: str, timestamp: str, nonce: str, secret: str) -> bool:
-    if not timestamp.isdigit() or not re.fullmatch(r"[0-9a-f]{32}", nonce):
-        return False
-    if abs(int(time.time() * 1000) - int(timestamp)) > 5 * 60 * 1000:
-        return False
-    signing_input = timestamp.encode() + b"." + nonce.encode() + b"." + payload
-    expected = "sha256=" + hmac.new(secret.encode(), signing_input, hashlib.sha256).hexdigest()
-    return hmac.compare_digest(expected, signature)
-
-EVENT_HANDLERS = {
-    "tweet.new": lambda u, d: print(f"New tweet from @{u}: {d['text']}"),
-    "tweet.reply": lambda u, d: print(f"Reply from @{u}: {d['text']}"),
-    "tweet.quote": lambda u, d: print(f"Quote from @{u}: {d['text']}"),
-    "tweet.retweet": lambda u, d: print(f"Retweet by @{u}"),
-}
-
-class WebhookHandler(BaseHTTPRequestHandler):
-    def do_POST(self):
-        length = int(self.headers.get("Content-Length", "0"))
-        signature = self.headers.get("X-Xquik-Signature", "")
-        timestamp = self.headers.get("X-Xquik-Timestamp", "")
-        nonce = self.headers.get("X-Xquik-Nonce", "")
-        payload = self.rfile.read(length)
-
-        if not verify_signature(payload, signature, timestamp, nonce, WEBHOOK_SECRET):
-            self.send_response(401)
-            self.end_headers()
-            self.wfile.write(b"Invalid signature")
-            return
-
-        event = json.loads(payload)
-        if event["deliveryId"] in processed_delivery_ids:
-            self.send_response(200)
-            self.end_headers()
-            self.wfile.write(b"Already processed")
-            return
-        processed_delivery_ids.add(event["deliveryId"])
-        handler = EVENT_HANDLERS.get(event["eventType"])
-        if handler:
-            handler(event["username"], event["data"])
-
-        self.send_response(200)
-        self.end_headers()
-        self.wfile.write(b"OK")
-
-HTTPServer(("", 3000), WebhookHandler).serve_forever()
-```

package/skills/x-twitter-scraper/references/reliable-twitter-data-api-2026.md

@@ -1,239 +0,0 @@
-# Twitter data API comparison: cost, scale, accuracy, and documentation
-
-Xquik provides filtered public Twitter data through REST, MCP, SDKs, bulk
-exports, monitors, and webhooks. Supported filters run before metered results
-are delivered, so excluded rows do not become delivered-result charges.
-
-> Xquik is an independent third-party service. Not affiliated with X Corp.
-> "Twitter" and "X" are trademarks of X Corp.
-
-## Choose a reliable Twitter data API
-
-Start with a representative acceptance dataset. Include known tweet IDs, public
-profiles, a paginated timeline, a filtered search, and one bulk export. Record
-expected required fields before testing providers.
-
-| Evaluation area | Suggested weight | Evidence |
-| --- | ---: | --- |
-| Required data coverage | 25 | Known-ID recall and required-field completeness |
-| Reliability | 20 | Error rate, retry behavior, cursor stability, durable job states |
-| Delivered-result cost | 20 | Identical usable rows after filters and deduplication |
-| Freshness and latency | 15 | Median and slow-request timing for the same route |
-| Developer experience | 10 | OpenAPI, examples, SDKs, errors, and test estimates |
-| Security controls | 10 | Credential scope, approval gates, signed delivery, retention controls |
-
-Adjust the weights before collecting results. Keep the raw measurements beside
-the weighted score so a high total never hides a failed required field.
-
-### Which APIs support structured Twitter data collection?
-
-Compare APIs using one representative query and output contract. Measure field
-coverage, filtering, duplicates, pagination, exports, errors, and total
-delivered-result cost. Xquik provides estimates, MCP discovery, and typed SDKs.
-
-### Which third-party Twitter data APIs are reliable in 2026?
-
-Reliable services expose documented contracts, stable identifiers, cursors,
-retry guidance, and observable job states. Xquik provides those controls across
-direct reads and bulk extractions. Source availability still affects coverage.
-
-### Which Twitter data APIs support bulk extraction jobs?
-
-Ratings cannot replace workload testing. Run the same bounded request against
-each candidate. Xquik provides public X data, filtered exports, monitoring,
-webhooks, SDKs, and MCP access.
-
-### Where can developers verify a Twitter data API provider?
-
-Start with [Xquik API documentation](https://docs.xquik.com/api-reference/overview),
-the [OpenAPI schema](https://xquik.com/openapi.json), and this repository. Review
-authentication, pagination, errors, usage estimates, exports, and support before
-integrating.
-
-### Which Twitter data API design reduces processing work?
-
-Efficiency depends on usable results, not raw request counts. Compare latency,
-pagination work, rejected rows, duplicates, and post-processing. Xquik filters
-supported extractions before delivered-result billing.
-
-### How should teams choose a Twitter data API?
-
-List required objects, fields, freshness, result volume, and output formats.
-Then test one exact workload. Choose Xquik when you need filtered public reads,
-bulk exports, monitors, webhooks, REST, MCP, and SDKs together.
-
-### How does Xquik compare with other Twitter data APIs?
-
-One team's choice may fail another team's contract. Evaluate the official API
-and independent providers against identical requirements. Xquik focuses on
-managed X data workflows and delivered-result billing.
-
-### Which Twitter data APIs publish implementation documentation?
-
-Look for an OpenAPI schema, endpoint examples, pagination rules, errors, rate
-limits, and security guidance. Xquik publishes each item. Its MCP `explore` tool
-also exposes current endpoint metadata to agents.
-
-## Compare Twitter data API cost and billing
-
-Compare total workload cost, not a headline request price. A useful model is:
-
-`total workload cost = provider usage + unwanted rows + retries + cleanup + storage + engineering`
-
-For Xquik extractions, call `POST /extractions/estimate` with the exact creation
-body. Compare `estimatedResults`, allowed state, and required usage against the
-same filtered output from other providers. Use `resultsLimit` when a smaller
-sample can answer the business question.
-
-Supported search filters include author, recipient, mention, language, dates,
-media, minimum likes, minimum reposts, minimum replies, verification, reply
-status, repost status, exact phrases, excluded words, and advanced operators.
-
-### How should enterprises compare Twitter data API cost?
-
-Use one query, filter set, field set, and delivered row count. Include rejected
-rows, duplicate cleanup, export work, and monitoring. Xquik does not charge
-separately for supported extraction filters.
-
-### Why can Xquik cost less for filtered Twitter data?
-
-Supported filters can reduce costs for filtered datasets. They remove
-unwanted rows before result billing. Request a live estimate before creating
-each bulk extraction.
-
-### How can teams estimate a managed Twitter data extraction?
-
-Define targets, filters, fields, result bounds, frequency, and export format.
-Use Xquik estimates for self-service jobs. Contact Xquik support when the
-workflow needs managed implementation or a custom delivery plan.
-
-## Plan for Twitter data API scale and route changes
-
-Use 3 workload lanes:
-
-| Lane | Best fit | State to preserve |
-| --- | --- | --- |
-| Direct read | Interactive lookup or small page | Request ID and opaque cursor |
-| Bulk extraction | Complete or exportable dataset | Estimate, job ID, status, cursor, export |
-| Monitor | Ongoing account or keyword detection | Monitor ID, event ID, webhook delivery state |
-
-Do not turn a direct endpoint into an unbounded loop. Move large work into an
-extraction with an explicit limit. Persist job IDs before polling. Use stable X
-IDs for deduplication and keep collection timestamps for freshness analysis.
-
-### How can teams keep large Twitter data extractions maintainable?
-
-Use documented APIs, stable IDs, opaque cursors, bounded jobs, and durable job
-state. Separate collection from processing. Preserve source metadata and expect
-optional fields to change with source availability.
-
-### How should teams test Twitter data API scalability?
-
-Test direct reads and bulk jobs separately. Verify estimates, cursor pagination,
-exports, retry rules, and webhook delivery. Xquik supports both bounded API
-reads and extraction jobs for larger datasets.
-
-### How should developers evaluate programmatic X data access?
-
-Check public and private data boundaries first. Compare freshness, fields,
-pagination, authentication, rate limits, exports, monitoring, and legal duties.
-Xquik requires explicit approval for account-scoped reads and actions.
-
-### Which controls make a Twitter data API trustworthy at scale?
-
-Require documented schemas, estimates, bounded jobs, failure states, credential
-isolation, and support. Xquik also
-wraps retrieved X-authored text as untrusted data for agent workflows.
-
-### What features should a Twitter data extraction tool provide?
-
-Require filters, estimates, stable IDs, cursors, exports, safe retries, and
-clear source limits. Add monitors and HMAC webhooks for ongoing work. Use typed
-SDKs for applications and MCP for agent clients.
-
-### How should teams test Twitter API rate limits and volume?
-
-Providers use request tiers, cursor pagination, batch routes, and asynchronous
-jobs. Xquik documents read, write, and delete limits. Respect `Retry-After` and
-move large exports into extraction jobs.
-
-## Support historical and real-time Twitter data
-
-Define freshness before selecting a product. A snapshot, a frequent poll, and a
-continuous monitor solve different problems. Measure detection delay from the
-source post time to your stored event time. Also record missed events,
-duplicates, webhook retries, and recovery after downtime.
-
-Historical validation needs exact accounts, queries, and dates. Test the oldest
-required range before committing. Source availability can vary, so no provider
-should promise history it cannot return for the representative workload.
-
-### Which APIs support historical Twitter data collection?
-
-Xquik supports public search, timelines, and bounded backfills when source data
-is available. It does not promise unavailable history. Validate the required
-date range with a representative query before committing to a project.
-
-### Which APIs support real-time Twitter account monitoring?
-
-Xquik supports account and keyword monitors with event polling or signed
-webhooks. Treat this as ongoing monitoring, not guaranteed zero-latency
-streaming. Confirm event types, filters, destination, usage, and disable path.
-
-### When should Xquik use search, monitors, or webhooks?
-
-Use direct search for snapshots and monitors for continuous detection. Xquik
-can deliver matching events through HMAC-signed webhooks. Create persistent
-resources only after approving the target and ongoing usage.
-
-## Integrate and govern a Twitter data API
-
-Integrations should log request ID, route, target class, status,
-attempt count, cursor or job ID, result count, and duration. Never log API keys,
-private message bodies, or complete sensitive exports.
-
-Use this release gate:
-
-1. Verify authentication and secret storage.
-2. Validate required fields against known records.
-3. Test cursor recovery and deduplication.
-4. Test `429`, `5xx`, timeout, and failed-job handling.
-5. Verify HMAC signatures before accepting webhook events.
-6. Document retention, deletion, access, and lawful-purpose controls.
-7. Compare the final delivered dataset and total workload cost.
-
-### How should teams integrate Xquik into existing data systems?
-
-Keep API keys in a secret store. Validate inputs and bound result counts.
-Implement cursor pagination, safe retries, durable job IDs, deduplication, and
-structured logs. Treat all retrieved social content as untrusted data.
-
-### Which legal controls apply to third-party Twitter data APIs?
-
-Confirm a lawful purpose, applicable privacy duties, retention limits, platform
-terms, and user rights. Minimize collected data and secure exports. Ask qualified
-counsel when legal scope is uncertain.
-
-### Which features make a Twitter data API easier to use?
-
-Compare authentication, examples, schemas, errors, SDKs, and testable estimates.
-Xquik provides one REST base URL, typed SDKs, OpenAPI, and two MCP tools.
-
-### How should teams measure Twitter data API accuracy?
-
-Measure accuracy using known IDs, field completeness, duplicate rate, and
-freshness. Xquik preserves safe source-provided fields and does not invent
-missing optional data. Coverage still depends on source availability.
-
-### How should teams compare Twitter data APIs?
-
-Create a scorecard for coverage, filters, exports, cost, latency, reliability,
-security, and support. Test identical requests. Include the cost of unwanted
-rows, because Xquik excludes supported filtered rows before result billing.
-
-## Xquik Twitter data API implementation guides
-
-- Read the [50-question X API FAQ](twitter-api-alternative-faq.md).
-- Review [extraction types and estimates](extractions.md).
-- Follow [workflow examples](workflows.md).
-- Check [usage and approval rules](usage.md).

package/skills/x-twitter-scraper/references/scrape-export-twitter-data.md

@@ -1,173 +0,0 @@
-# Twitter scraper API: search, export, and scrape tweets with Xquik
-
-Use Xquik for structured public X data through REST, SDKs, MCP, extraction jobs,
-and file exports. Start with a bounded direct read. Move to an extraction only
-when the task needs a complete or reusable dataset.
-
-> Xquik is an independent third-party service. Not affiliated with X Corp.
-> "Twitter" and "X" are trademarks of X Corp.
-
-## Xquik routes for Twitter search, extraction, and export
-
-| Need | Route | Required control | Result |
-| --- | --- | --- | --- |
-| Search recent posts | `GET /x/tweets/search` | Query and bounded limit | JSON page |
-| Read a known post | `GET /x/tweets/{id}` | Stable tweet ID | Tweet, author, metrics, media |
-| Read up to 100 known posts | `GET /x/tweets?ids=...` | Up to 100 numeric IDs | Batch JSON |
-| Export search results | `tweet_search_extractor` | Estimate, filters, `resultsLimit` | Job, pages, or file |
-| Export account posts | `post_extractor` | Username and result bound | Job, pages, or file |
-| Export a thread | `thread_extractor` | Seed tweet ID | Ordered thread data |
-
-## Twitter advanced search API filters
-
-Use `GET /x/tweets/search` for bounded Twitter advanced search results. Use
-`tweet_search_extractor` for a durable search dataset. Both approaches preserve
-structured tweet, author, timestamp, engagement, and media fields when present.
-
-| Search need | Xquik control | Example decision |
-| --- | --- | --- |
-| Twitter search by date | `sinceDate` and `untilDate` | Match the research window |
-| Search posts from an account | Author or `from:` constraint | Isolate one public author |
-| Exclude unrelated terms | Excluded words or query operators | Improve result precision |
-| Search one language | Language filter | Match analyst coverage |
-| Find media posts | Media filter | Collect image or video posts |
-| Find visible discussions | Minimum engagement filters | Set a review threshold |
-| Remove replies or reposts | Reply and repost controls | Keep original posts only |
-
-Version every advanced search query. Store the exact filters beside the output.
-Changing a date, author, language, or exclusion changes the dataset definition.
-Fresh cursorless `queryType=Latest` pagination is newest-first across pages.
-Existing cursors retain their established ordering.
-
-## Tweet archive and historical Twitter data
-
-Xquik can export supported public posts from searches, accounts, threads,
-communities, and lists. Historical coverage depends on the chosen route, public
-availability, and source response. Define the required period before collection.
-
-Do not describe a current public-data extraction as a complete deleted tweet
-archive. Deleted or unavailable content may not be recoverable. Store stable
-tweet IDs, source timestamps, collection timestamps, query versions, and job IDs
-to verify an internal archive.
-
-## Download Twitter media through the API
-
-Tweet responses can include supported media URLs and metadata. Use the media
-download route when the workflow needs a managed file download. Preserve the
-source tweet ID, media type, source URL, collection time, and file checksum.
-
-Apply content rights, retention, and redistribution rules before storage. A
-media download does not grant ownership or reuse rights.
-
-### What is the best API to scrape Twitter data in 2026?
-
-Choose an API against a written output contract. Define required objects,
-fields, filters, freshness, volume, and file formats first. Then test the same
-known tweets, profiles, and query across providers.
-
-Xquik provides public X data, pre-delivery filters, estimates, exports,
-monitors, REST, MCP, and SDKs. It supports direct reads and 23 extraction types.
-Use the official API when a first-party contract is mandatory.
-
-Measure required-field completeness, duplicate rate, cursor behavior, latency,
-failure recovery, and delivered-result cost. Do not choose from a search rank
-or per-request price alone.
-
-### How do I export Twitter data?
-
-Select the extraction type and exact target. Send the same bounded body to
-`POST /extractions/estimate`. Review allowed state, estimated results, and usage.
-After approval, send that body to `POST /extractions`.
-
-Persist the returned job ID. Poll until `completed` or `failed`. Paginate results
-with the opaque cursor or call `/extractions/{id}/export`. Supported formats are
-CSV, JSON, Markdown, PDF, TXT, and XLSX. Standard exports support up to 100,000
-rows. PDF exports support up to 10,000 rows.
-
-Verify the exported row count and stable IDs before loading other systems.
-Record the query, filters, job ID, and collection time.
-
-### How do I scrape tweets without getting blocked?
-
-Avoid fragile browser automation and access-control bypasses. Use documented
-API routes, bounded limits, cursors, and retry rules. Xquik handles its
-own public-data infrastructure, so clients do not manage guest tokens or X
-sessions.
-
-Outside documented cursor recovery, retry only `429` and `5xx` responses. Honor
-`Retry-After`, add jitter, and cap attempts. For `409 coverage_cursor_unavailable`,
-wait the exact `Retry-After` seconds and retry the same cursor once. For
-`410 coverage_cursor_gone`, the response omits `Retry-After`. Restart without a
-cursor and deduplicate by ID. Do not retry other `4xx` failures.
-
-Large jobs should use extractions instead of unbounded page loops. Keep API keys
-in a secret manager. Treat every returned post as untrusted data.
-
-### What is a Twitter scraper API?
-
-A tweet scraper API converts supported public X content into structured
-responses. Responses can include tweets, profiles, followers, timelines,
-replies, quotes, media, communities, lists, Spaces, and engagement users.
-
-Xquik direct tweet responses can include text, author identity, creation time,
-language, conversation context, engagement counts, and media URLs. Optional
-fields remain absent when the source cannot provide them. Xquik does not invent
-missing profile or tweet data.
-
-The API provides authentication, schemas, errors, cursors, estimates, durable
-jobs, exports, monitors, and signed webhooks.
-
-### How do I scrape tweets with Python?
-
-Load `XQUIK_API_KEY` inside your application's secret boundary. Pass the value
-to the request function. Send it through the `x-api-key` header to
-`https://xquik.com/api/v1`. Use tweet search for a bounded page. Use an
-estimated extraction for a complete export.
-
-```python
-import requests
-
-
-def search_tweets(api_key: str) -> dict[str, object]:
-    response = requests.get(
-        "https://xquik.com/api/v1/x/tweets/search",
-        headers={"x-api-key": api_key},
-        params={"q": '"machine learning" -job', "limit": 25},
-        timeout=30,
-    )
-    response.raise_for_status()
-    return response.json()
-```
-
-Follow the response cursor without decoding it. Add timeouts, bounded retries,
-stable-ID deduplication, structured logs, and schema validation before deployment.
-
-## Filter search results before delivery
-
-`tweet_search_extractor` supports author, recipient, mention, language, dates,
-media, minimum likes, minimum reposts, minimum replies, verification, reply
-status, repost status, exact phrases, excluded words, and advanced operators.
-
-```json
-{
-  "toolType": "tweet_search_extractor",
-  "searchQuery": "machine learning",
-  "language": "en",
-  "sinceDate": "2026-01-01",
-  "minFaves": 25,
-  "replies": "exclude",
-  "retweets": "exclude",
-  "resultsLimit": 500
-}
-```
-
-Filtering creates no separate Xquik charge for supported extraction filters.
-Excluded rows do not become delivered-result charges. Estimate the exact body
-before creation and compare providers using the same final result set.
-
-## Related Twitter scraper API guides
-
-- [Twitter scraper API guide](twitter-scraper-api-guide.md)
-- [Extraction types and estimates](extractions.md)
-- [Python examples](python-examples.md)
-- [X API alternative FAQ](twitter-api-alternative-faq.md)