kaitoinfra/twitterapi-io/twitterapi-io-read

twitterapi.io (read-only)

Read-only skill maintained by the twitterapi.io team. It covers public X/Twitter data only: it never logs in to an X account, never handles cookies, passwords or proxies, and never posts, likes, follows or sends messages.

twitterapi.io is an independent third-party REST API for public X data, not affiliated with X Corp. If you need X's own API, the official one is at https://developer.x.com.

When to use this skill

• Search posts with X search operators (from:, since_time:, min_faves:, lang: …)
• Look up user profiles, followers, followings
• Get a user's recent posts, replies, quote posts, retweeters, thread context
• Trends, lists, communities
• Build dashboards, research datasets or monitoring jobs on public data

Core facts

Security

Read the API key from the environment variable TWITTERAPI_IO_KEY. Never hardcode it, print it or commit it. If it is missing, ask the user to create one on the dashboard.

Minimal example

curl -s "https://api.twitterapi.io/twitter/user/info?userName=jack" \
  -H "x-api-key: $TWITTERAPI_IO_KEY"

import os, requests
BASE = "https://api.twitterapi.io"
HEADERS = {"x-api-key": os.environ["TWITTERAPI_IO_KEY"]}
r = requests.get(f"{BASE}/twitter/tweet/advanced_search",
                 headers=HEADERS,
                 params={"query": "from:jack", "queryType": "Latest"},
                 timeout=30)
r.raise_for_status()
for t in r.json().get("tweets", []):
    print(t["createdAt"], t["text"][:80])

Read endpoints

Parameter names differ per endpoint (some camelCase, some snake_case). Copy them exactly as shown.

Patterns

Pagination

List endpoints return has_next_page and next_cursor. Pass next_cursor back as cursor; stop when has_next_page is false. Always set a page limit so a bug can't page forever.

Errors

• 400 → a required parameter is missing or the search query is invalid (the response detail says what to fix)
• 401 / 403 → missing or wrong x-api-key
• 402 → out of credits; stop and tell the user to top up (don't retry)
• 429 → rate-limited; retry with backoff
• 5xx → transient; retry with backoff

Cost awareness

Each call is billed. Before a loop that could run long (all followers of a large account, months of search), estimate the number of calls and confirm with the user.

Anti-patterns

• Don't normalise parameter names; copy them from the table
• Don't retry on 402
• Don't log or commit the API key