twitr-sh Search API

openapi: 3.2.0
info:
  title: twitr.sh Search API
  version: 1.0.0
  contact:
    email: support@twitr.sh
  description: 'Pay-per-call X/Twitter data API for AI agents: single-object reads, tweet/user search, timelines, lists, communities, bulk extractions (23 tools, async with downloadable datasets), real-time account/keyword monitors (prepaid hours; events via free polling or signed webhooks), giveaway draws, trend radar, and an AI tweet composer. No signup — the wallet is the account; an optional API key (Authorization: Bearer) spends a prepaid card balance instead. Payment via x402 v2 (USDC on Base/Solana) and MPP (USDC on Tempo). Per-result reads use x402 upto on Base only: the 402 quotes a maximum, empty results cost $0, and non-empty calls have a $0.0024 minimum. Volume tools bill per returned item against a mandatory resultsLimit; extractions and monitors settle before dispatch.'
  x-guidance: 'All tools are POST /api/tools/{tool} and return 402 with payment options on first call (Base upto only for per-result reads; fixed operations can offer exact x402 and MPP); pay and retry to receive data. Volume tools (x_search, x_timeline, x_lists, x_communities non-info kinds, followers-you-know) REQUIRE resultsLimit (integer 1–10000) — you are billed per returned item and the cap is enforced upstream. x_extract is async: it returns {snapshot_id, status_url}; poll GET /api/snapshots/{id} (free, SIWX) until status=ready for a download_url. x_monitor is PREPAID by the hour: it stops at expires_at unless extended — extend early, never expect refunds on deletion; events flow to GET /api/monitors/{id}/events (free, SIWX) or your registered webhook (/api/webhooks, signed with X-Twitr-Signature). draws, x_extract and x_monitor require an Idempotency-Key header. radar + compose are flat floor-priced. GET /api/snapshots and GET /api/monitors (SIWX) list the wallet''s history for free. Errors are RFC 9457 Problem bodies (components.schemas.Problem) with machine-actionable `retryable` and `hint` fields — retryable:true means retry the SAME request unchanged after a backoff; x402 reads settle after success; prepaid operations can fail after payment. Alternative to per-call payment: send `Authorization: Bearer tw_live_…` (an API key created at /dashboard) and each call is charged to that account''s prepaid USD balance at the same prices — per-result reads charge only returned records; the free SIWX endpoints accept the same key.'
servers:
- url: https://twitr.sh
tags:
- name: Search
paths:
  /api/tools/x_search:
    post:
      operationId: x_search
      summary: X/Twitter Search
      description: Search X/Twitter tweets with the full operator set — keyword, exact phrase, from-user, language, date range, media type, minimum likes/retweets, verified-only — or search user profiles by keyword. Billed per tweet returned against your resultsLimit cap. Built for tracking what people say about a topic, brand, or ticker in real time.
      tags:
      - Search
      x-guidance: 'type=search-tweets (default): q required, resultsLimit MANDATORY (billed per tweet returned). Supports the full filter set: fromUser, language, sinceDate/untilDate, mediaType, minFaves, verifiedOnly, exactPhrase, excludeWords, advancedQuery, and more. type=search-users: q required; returns one results page per call — follow report.next_cursor for the next page (each page is a separate paid call).'
      x-ux-hints: 'Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. Read failures before x402 settlement are not charged. Prepaid operations can fail after payment; inspect their receipt.'
      x-payment-info:
        authMode: paid
        price:
          mode: dynamic
          currency: USD
          min: '0.002400'
          max: '1.200000'
        protocols:
        - x402:
            network: base
            asset: USDC
        - x402:
            network: solana
            asset: USDC
        - mpp:
            method: usdc
            intent: charge
            currency: USD
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: Search tweets (default) or users.
                  enum:
                  - search-tweets
                  - search-users
                q:
                  type: string
                  description: Search query (X operator syntax supported for tweets).
                resultsLimit:
                  type: integer
                  description: 'search-tweets: MANDATORY max tweets returned, billed per tweet.'
                  minimum: 1
                  maximum: 10000
                cursor:
                  type: string
                  description: 'search-users: pagination cursor from a previous call''s report.next_cursor.'
                fromUser:
                  type: string
                language:
                  type: string
                sinceDate:
                  type: string
                  description: YYYY-MM-DD
                untilDate:
                  type: string
                  description: YYYY-MM-DD
                mediaType:
                  type: string
                  enum:
                  - images
                  - videos
                  - gifs
                  - media
                minFaves:
                  type: integer
                minRetweets:
                  type: integer
                minReplies:
                  type: integer
                verifiedOnly:
                  type: boolean
                exactPhrase:
                  type: string
                excludeWords:
                  type: string
                advancedQuery:
                  type: string
                  description: Raw X search operator string appended to q.
              required:
              - q
              allOf:
              - if:
                  properties:
                    type:
                      const: search-users
                then: {}
                else:
                  required:
                  - resultsLimit
            example:
              q: artificial intelligence
              type: search-tweets
              resultsLimit: 50
              language: en
              minFaves: 100
      responses:
        '200':
          description: Result dataset.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Array of returned items. Shape varies per tool — see each tool's documentation.
                    items:
                      type: object
                  runId:
                    type: string
                    description: Run ID for debugging/audit.
                  duration:
                    type: integer
                    description: Run duration in seconds.
                required:
                - items
              example:
                items:
                - id: '1893710452812718080'
                  text: This is a great thread, thanks for sharing.
                  authorUsername: elonmusk
                  likeCount: 1180
                  createdAt: '2026-02-24T10:05:00.000Z'
                runId: tw_example
                duration: 2
                payment:
                  protocol: x402
                  amount: '0.060000'
                  currency: USD
        '202':
          description: Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only).
        '400':
          description: Bad request — missing resultsLimit or Idempotency-Key where required. Body is a Problem with `retryable:false` and a `hint`; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '402':
          description: 'Payment Required. Per-result reads require x402 upto on Base: authorize the maximum and pay only for delivered records, with a $0.0024 non-empty minimum and zero for empty results. Fixed-price operations may additionally offer exact x402 and MPP.'
        '403':
          description: Acting handle not connected to this wallet — connect it via /api/x-accounts/start first; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Unknown tool path — GET /openapi.json for the valid list; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limited — `retryable:true`; retry unchanged after the Retry-After header; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Unexpected handler error — inspect payment receipt before retrying.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Upstream provider error — `retryable:true`; inspect payment receipt before retrying; prepaid operations may already be charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service capacity temporarily unavailable — `retryable:true`; retry later; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    Problem:
      type: object
      description: RFC 9457 Problem Details, extended with machine-actionable recovery fields. Every non-2xx body from /api/tools/* uses this shape. x402 reads settle after success. Prepaid operations can fail after payment; inspect the receipt.
      properties:
        type:
          type: string
          description: Problem type URI (https://paymentauth.org/problems/{code}).
        title:
          type: string
          description: Human-readable summary of the problem class.
        status:
          type: integer
          description: HTTP status code, repeated in the body.
        detail:
          type: string
          description: What went wrong on this specific call.
        error:
          type: string
          description: Machine code (snake_case), e.g. records_cap_required, rate_limited.
        message:
          type: string
          description: Legacy alias of detail.
        retryable:
          type: boolean
          description: True when the SAME request, unchanged, may succeed if retried later (rate limit, capacity, transient upstream). False when the request must change first.
        hint:
          type: string
          description: One actionable next step for the calling agent.
        retry_after_seconds:
          type: integer
          description: 'Present on 429: seconds to wait before retrying.'
      required:
      - type
      - title
      - status
  securitySchemes:
    siwx:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X
      description: Sign-In-With-X (CAIP-122). Base64-encoded CAIP-122 payload signed by the caller's wallet. Server recovers the signer address cryptographically; any client-supplied wallet parameter is ignored.
    bearerKey:
      type: http
      scheme: bearer
      description: Optional API key (tw_live_…) created in the dashboard. Paid tools charge the key owner's prepaid USD balance instead of an on-chain payment; free endpoints accept it in place of SIWX.
    publicRead:
      type: apiKey
      in: query
      name: _public
      description: No-op placeholder. This endpoint requires no authentication; the scheme exists so validators that want a named security reference on public operations have one to point at.
x-ux-hints: Confirm with the user before any call that quotes above $0.10 or requests resultsLimit >= 500. Never spin a background poll loop — when the user asks progress on an extraction, call /api/snapshots/{id} (free, SIWX). Send Idempotency-Key with paid calls so a dropped response is replayed from cache (10 min) instead of re-running. Wallet history is free — use it when the user asks 'what have I extracted?'.
x-service-info:
  categories:
  - data
  - social
  - search
  - developer-tools
  docs:
    homepage: https://twitr.sh
    apiReference: https://twitr.sh/openapi.json
    llms: https://twitr.sh/llms.txt
x-discovery:
  ownershipProofs: []