{"openapi":"3.1.0","info":{"title":"Xquik API","version":"1.0","description":"Not affiliated with X Corp. Look up any tweet, user, or trend on X. Search tweets, check follower relationships, download media, and monitor accounts in real time. 33 paid-read endpoints work without a subscription through prepaid credits. 7 fixed-price lookups also accept direct per-call MPP payments. Write endpoints (post, like, retweet, follow, DM) and automation endpoints (bulk extractions, giveaway draws, monitors, webhooks) require an API key or OAuth 2.1 bearer token.\n\n## Xquik SDKs\n\nAll SDKs are auto-generated from this OpenAPI spec via Stainless and stay in sync release-by-release. Pick your language:\n\n- TypeScript / Node.js: `npm i x-twitter-scraper` -\n  [Xquik-dev/x-twitter-scraper-typescript](https://github.com/Xquik-dev/x-twitter-scraper-typescript)\n\n- Python: `pip install x-twitter-scraper` -\n  [Xquik-dev/x-twitter-scraper-python](https://github.com/Xquik-dev/x-twitter-scraper-python)\n\n- Go: `go get github.com/Xquik-dev/x-twitter-scraper-go` -\n  [Xquik-dev/x-twitter-scraper-go](https://github.com/Xquik-dev/x-twitter-scraper-go)\n\n- Ruby: `gem install x-twitter-scraper` -\n  [Xquik-dev/x-twitter-scraper-ruby](https://github.com/Xquik-dev/x-twitter-scraper-ruby)\n\n- Java (source build; Maven Central pending) -\n  [Xquik-dev/x-twitter-scraper-java](https://github.com/Xquik-dev/x-twitter-scraper-java)\n\n- Kotlin (source build; Maven Central pending) -\n  [Xquik-dev/x-twitter-scraper-kotlin](https://github.com/Xquik-dev/x-twitter-scraper-kotlin)\n\n- C# / .NET: `dotnet add package XTwitterScraper` -\n  [Xquik-dev/x-twitter-scraper-csharp](https://github.com/Xquik-dev/x-twitter-scraper-csharp)\n\n- PHP: `composer require xquik/x-twitter-scraper` -\n  [Xquik-dev/x-twitter-scraper-php](https://github.com/Xquik-dev/x-twitter-scraper-php)\n\n- CLI: `npm i -g x-twitter-scraper-cli` -\n  [Xquik-dev/x-twitter-scraper-cli](https://github.com/Xquik-dev/x-twitter-scraper-cli)\n\n- Terraform Provider (Terraform Registry) -\n  [Xquik-dev/terraform-provider-x-twitter-scraper](https://github.com/Xquik-dev/terraform-provider-x-twitter-scraper)\n\n\nOpenClaw plugin: [Xquik-dev/tweetclaw](https://github.com/Xquik-dev/tweetclaw) (`claw install tweetclaw`).","x-guidance":"## Common tasks\n\n**Find a tweet** - GET /x/tweets/{id} with a numeric tweet ID. Returns full tweet data: text, author, metrics (likes, retweets, replies, views), media URLs, and creation timestamp. Cost: $0.00015 per lookup.\n\n**Search tweets** - GET /x/tweets/search?q={query}&limit={n}. Supports X search operators, structured filters like fromUser, mediaType, minFaves, hashtags, and verifiedOnly, plus exact lookup for a pasted Tweet ID or X status URL. Plain from:user date windows are optimized for timeline completeness. Returns up to 200 tweets per page with cursor-based pagination. Cost: $0.00015 per tweet returned.\n\n**Find a user** - GET /x/users/{id} where {id} is a numeric user ID or @username. Returns profile data: name, bio, follower/following counts, verification status, join date. Cost: $0.00015 per lookup.\n\n**Check if A follows B** - GET /x/followers/check?source={a}&target={b} where source and target are usernames, @usernames, or X or Twitter profile URLs. Cost: $0.00075.\n\n**Get trending topics** - GET /trends?woeid={region}&count={n}. WOEID 1 = worldwide, 23424977 = US, 23424975 = UK, 23424969 = Turkey. Cost: $0.00045.\n\n**Download media** - POST /x/media/download with {\"tweetIds\": [\"123\", \"456\"]} body. Returns download URLs for images and videos. Cost: 1 credit per fresh tweet processed with media; cached repeat downloads are free.\n\n**Read an article** - GET /x/articles/{tweetId} for long-form X Articles. Returns full article HTML, cover image, and metadata. Cost: $0.00075.\n\n## Pagination\n\nDefault v1 responses keep their existing pagination fields for compatibility. Platform list endpoints return `hasMore` and `nextCursor`; X data endpoints return `has_next_page` and `next_cursor`. Send `xquik-api-contract: 2026-04-29` to receive the unified best-practice fields `has_more` and `next_cursor`. Pass the cursor back as `?cursor={cursor}`; legacy `?after={cursor}` still works. Dynamic-priced endpoints charge per item returned, not per request.\n\n## Authentication\n\nEligible paid read endpoints accept accountless Stripe credit wallets. Fixed-price lookups also accept direct MPP payments. Media downloads, write endpoints, and automation features require authentication. Send an Xquik API key through `x-api-key`, `Xquik-Api-Key`, or `Authorization: Bearer xq_...`. Send an OAuth 2.1 access token through `Authorization: Bearer`.\n\n## Best-Practice Response Contract\n\nv1 keeps its original response contract by default so existing integrations do not break. Send `xquik-api-contract: 2026-04-29` to opt in to the best-practice contract: snake_case response fields, Unix timestamps in seconds, structured error objects, `has_more` and `next_cursor` pagination fields, `object` resource identifiers, and prefixed IDs where available. Dependency failures that returned 502 in default v1 return 424 in the opt-in contract. Future major API versions should make this contract the default.","contact":{"name":"Xquik","url":"https://xquik.com","email":"support@xquik.com"}},"servers":[{"url":"https://xquik.com"}],"x-service-info":{"categories":["data"],"docs":{"homepage":"https://xquik.com","apiReference":"https://docs.xquik.com","llms":"https://docs.xquik.com/llms.txt"}},"x-discovery":{"ownershipProofs":["dns:xquik.com"]},"security":[{"apiKey":[]},{"oauthBearer":[]}],"tags":[{"name":"API Keys","description":"API key management (session auth only)"},{"name":"Account","description":"Account info and settings"},{"name":"Articles","description":"Long-form X Article extraction"},{"name":"Communities","description":"X Community info, members, and tweets"},{"name":"Composition","description":"AI tweet composition, drafts, writing styles, and radar"},{"name":"Draws","description":"Giveaway draws from tweet replies"},{"name":"Events","description":"Activity events from monitored accounts"},{"name":"Extractions","description":"Bulk data extraction (23 tool types)"},{"name":"Guest Wallets","description":"Accountless prepaid access for paid read endpoints"},{"name":"Lists","description":"X List followers, members, and tweets"},{"name":"Media","description":"Media upload and download"},{"name":"Monitors","description":"Real-time X account monitoring"},{"name":"Subscribe","description":"Subscription, billing, and credits"},{"name":"Support","description":"Support ticket management"},{"name":"Trends","description":"Trending topics and hashtags by region"},{"name":"Tweets","description":"Look up, search, and analyze individual tweets"},{"name":"Users","description":"Look up, search, and explore user profiles and relationships"},{"name":"Webhooks","description":"Webhook endpoint management and delivery"},{"name":"X Accounts","description":"Connected X account management"},{"name":"X Write","description":"X write actions (tweets, likes, follows, DMs)"}],"paths":{"/api/v1/account":{"get":{"operationId":"getAccount","summary":"Get account info","tags":["Account"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"responses":{"200":{"description":"Account info","content":{"application/json":{"schema":{"type":"object","required":["plan","monitorsUsed","monitorsAllowed","monitorBilling"],"properties":{"plan":{"type":"string","enum":["active","inactive"],"example":"active"},"monitorsUsed":{"type":"integer","example":3},"monitorsAllowed":{"type":"integer","deprecated":true,"x-stainless-deprecation-message":"Monitor slots are unlimited. Use monitorBilling.unlimitedSlots instead.","description":"Deprecated. Monitor slots are unlimited, so this is always Number.MAX_SAFE_INTEGER.","example":9007199254740991},"monitorBilling":{"type":"object","required":["activeDailyEstimate","activeHourlyBurn","creditsPerActiveMonitorDay","creditsPerActiveMonitorHour","eventsIncluded","instantCheckIntervalSeconds","unlimitedSlots"],"properties":{"activeDailyEstimate":{"type":"string","description":"Estimated daily credits for currently active monitors.","example":"1500"},"activeHourlyBurn":{"type":"string","description":"Credits charged each hour for currently active monitors.","example":"63"},"creditsPerActiveMonitorDay":{"type":"string","description":"Estimated daily credits for 1 active instant monitor.","example":"500"},"creditsPerActiveMonitorHour":{"type":"string","description":"Hourly credits charged for 1 active instant monitor.","example":"21"},"eventsIncluded":{"type":"boolean","description":"Webhook and event deliveries are included in monitor billing.","example":true},"instantCheckIntervalSeconds":{"type":"integer","description":"Active monitors check every 1 second.","example":1},"unlimitedSlots":{"type":"boolean","description":"Monitor slot count is unlimited.","example":true}}},"creditInfo":{"type":"object","required":["balance","lifetimePurchased","lifetimeUsed","autoTopupEnabled","autoTopupAmountDollars","autoTopupThreshold"],"properties":{"balance":{"type":"string","description":"Bigint string to preserve precision above Number.MAX_SAFE_INTEGER.","example":"50000"},"lifetimePurchased":{"type":"string","description":"Total purchased credits as a bigint string.","example":"140000"},"lifetimeUsed":{"type":"string","description":"Total consumed credits as a bigint string.","example":"90000"},"autoTopupEnabled":{"type":"boolean","example":false},"autoTopupAmountDollars":{"type":"number","description":"Dollar amount charged when automatic top-up runs.","example":10},"autoTopupThreshold":{"type":"string","description":"Bigint string threshold that triggers automatic top-up when enabled.","example":"50000"}},"example":{"balance":"50000","lifetimePurchased":"140000","lifetimeUsed":"90000","autoTopupEnabled":false,"autoTopupAmountDollars":10,"autoTopupThreshold":"50000"}},"xUsername":{"type":"string","description":"Linked X username, omitted when no X account is connected.","example":"elonmusk"}}},"example":{"plan":"active","monitorsUsed":3,"monitorsAllowed":9007199254740991,"monitorBilling":{"activeDailyEstimate":"1500","activeHourlyBurn":"63","creditsPerActiveMonitorDay":"500","creditsPerActiveMonitorHour":"21","eventsIncluded":true,"instantCheckIntervalSeconds":1,"unlimitedSlots":true},"creditInfo":{"balance":"50000","lifetimePurchased":"140000","lifetimeUsed":"90000","autoTopupEnabled":false,"autoTopupAmountDollars":10,"autoTopupThreshold":"50000"},"xUsername":"elonmusk"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"patch":{"operationId":"updateAccount","summary":"Update account locale","tags":["Account"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"Locale preference for the account.","content":{"application/json":{"schema":{"type":"object","required":["locale"],"properties":{"locale":{"type":"string","enum":["en","tr","es"],"example":"en"}}},"example":{"locale":"en"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/account/x-identity":{"put":{"operationId":"setXIdentity","summary":"Set linked X username","tags":["Account"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"X username to link to this account.","content":{"application/json":{"schema":{"type":"object","required":["username"],"properties":{"username":{"type":"string","description":"X username without @","example":"elonmusk"}}},"example":{"username":"elonmusk"}}}},"responses":{"200":{"description":"X identity linked","content":{"application/json":{"schema":{"type":"object","required":["success","xUsername"],"properties":{"success":{"type":"boolean","const":true},"xUsername":{"type":"string","example":"elonmusk"}}},"example":{"success":true,"xUsername":"elonmusk"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/api-keys":{"get":{"operationId":"listApiKeys","summary":"List API keys","tags":["API Keys"],"security":[{"cookieSession":[]}],"responses":{"200":{"description":"API key list","content":{"application/json":{"schema":{"type":"object","required":["keys"],"properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"},"example":[]}}},"example":{"keys":[]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"post":{"operationId":"createApiKey","summary":"Create API key","tags":["API Keys"],"security":[{"cookieSession":[]}],"requestBody":{"required":true,"description":"Optional display name for the new API key.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"My API Key"}}},"example":{"name":"My API Key"}}}},"responses":{"201":{"description":"API key created","content":{"application/json":{"schema":{"type":"object","required":["id","fullKey","name","prefix","createdAt"],"properties":{"id":{"type":"string","example":"42"},"fullKey":{"type":"string","example":"xq_live_abc123def456"},"name":{"type":"string","example":"My API Key"},"prefix":{"type":"string","example":"xq_live_abc1"},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"}}},"example":{"id":"42","fullKey":"xq_live_abc123def456","name":"My API Key","prefix":"xq_live_abc1","createdAt":"2025-01-15T12:00:00Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"API key limit reached","content":{"application/json":{"schema":{"type":"object","required":["error","limit","message"],"properties":{"error":{"type":"string","const":"api_key_limit_reached","example":"api_key_limit_reached"},"limit":{"type":"integer","example":100},"message":{"type":"string","example":"API key limit reached. Delete an existing key first."}}},"example":{"error":"api_key_limit_reached","limit":100,"message":"API key limit reached. Delete an existing key first."}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/api-keys/{id}":{"delete":{"operationId":"revokeApiKey","summary":"Revoke API key","tags":["API Keys"],"security":[{"cookieSession":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/subscribe":{"post":{"operationId":"subscribe","summary":"Create subscription checkout","description":"Create a subscription checkout or billing-management URL only after the user confirms. The request never completes payment by itself.\n","tags":["Subscribe"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":false,"description":"Optional subscription tier to pre-select at checkout.","content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","enum":["starter","pro","business"],"description":"Subscription tier to pre-select.","example":"pro"}}},"example":{"tier":"pro"}}}},"responses":{"200":{"description":"Billing URL","content":{"application/json":{"schema":{"type":"object","required":["url","status","message"],"properties":{"url":{"type":"string","format":"uri","example":"https://xquik.com/billing/session"},"status":{"type":"string","enum":["checkout_created","already_subscribed","payment_issue"],"example":"checkout_created"},"message":{"type":"string","example":"Billing session created"}}},"example":{"url":"https://xquik.com/billing/session","status":"checkout_created","message":"Billing session created"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/compose":{"post":{"operationId":"compose","summary":"Compose, refine, or score a tweet","tags":["Composition"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"Workflow step, topic, goal, and optional style parameters.","content":{"application/json":{"schema":{"type":"object","required":["step"],"properties":{"step":{"type":"string","enum":["compose","refine","score"],"description":"Workflow step","example":"compose"},"topic":{"type":"string","description":"Tweet topic (compose, refine)","example":"AI trends in 2025"},"goal":{"type":"string","enum":["engagement","followers","authority","conversation"],"description":"Optimization goal","example":"engagement"},"draft":{"type":"string","description":"Tweet draft text to evaluate (score)","example":"AI is changing everything. Here's why."},"tone":{"type":"string","description":"Desired tone (refine)","example":"professional"},"styleUsername":{"type":"string","description":"Cached style username for voice matching (compose)","example":"elonmusk"},"additionalContext":{"type":"string","description":"Extra context or URLs (refine)","example":"https://x.com/elonmusk/status/1234567890"},"callToAction":{"type":"string","description":"Desired call to action (refine)","example":"Follow for more"},"mediaType":{"type":"string","enum":["photo","video","none"],"description":"Media type (refine)","example":"none"},"hasLink":{"type":"boolean","description":"Whether a link is attached (score)","example":false},"hasMedia":{"type":"boolean","description":"Whether media is attached (score)","example":false}}},"example":{"step":"compose","topic":"AI trends in 2025","goal":"engagement"}}}},"responses":{"200":{"description":"Composition result","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"Generated or refined tweet text","example":"AI is reshaping every industry. Here are 5 trends to watch in 2025."},"score":{"type":"number","description":"Engagement score (0-100)","example":78},"feedback":{"type":"string","description":"AI feedback on the draft","example":"Strong hook. Consider adding a call to action."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Improvement suggestions","example":["Add a thread hook","Include a relevant hashtag"]}},"additionalProperties":true},"example":{"text":"AI is reshaping every industry. Here are 5 trends to watch in 2025.","score":78,"feedback":"Strong hook. Consider adding a call to action.","suggestions":["Add a thread hook","Include a relevant hashtag"]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/drafts":{"get":{"operationId":"listDrafts","summary":"List saved drafts","tags":["Composition"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"name":"afterCursor","in":"query","schema":{"type":"string"},"description":"Cursor for pagination"}],"responses":{"200":{"description":"Draft list","content":{"application/json":{"schema":{"type":"object","required":["drafts","hasMore"],"properties":{"drafts":{"type":"array","items":{"$ref":"#/components/schemas/Draft"},"example":[]},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","example":"abc123"}}},"example":{"drafts":[],"hasMore":false}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"post":{"operationId":"createDraft","summary":"Save a tweet draft","tags":["Composition"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"Draft text with optional topic and optimization goal.","content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","example":"AI is the future of productivity"},"topic":{"type":"string","example":"AI trends"},"goal":{"type":"string","enum":["engagement","followers","authority","conversation"],"example":"engagement"}}},"example":{"text":"AI is the future of productivity","topic":"AI trends","goal":"engagement"}}}},"responses":{"201":{"description":"Draft created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftDetail"},"example":{"id":"42","text":"AI is the future of productivity","topic":"AI trends","goal":"engagement","createdAt":"2025-01-15T12:00:00Z","updatedAt":"2025-01-16T09:30:00Z"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/drafts/{id}":{"get":{"operationId":"getDraft","summary":"Get draft by ID","tags":["Composition"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"Draft details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftDetail"},"example":{"id":"42","text":"AI is the future of productivity","topic":"AI trends","goal":"engagement","createdAt":"2025-01-15T12:00:00Z","updatedAt":"2025-01-16T09:30:00Z"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"delete":{"operationId":"deleteDraft","summary":"Delete a draft","tags":["Composition"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"204":{"$ref":"#/components/responses/NoContent"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/styles":{"get":{"operationId":"listStyles","summary":"List cached style profiles","tags":["Composition"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"responses":{"200":{"description":"Style profile list","content":{"application/json":{"schema":{"type":"object","required":["styles"],"properties":{"styles":{"type":"array","items":{"$ref":"#/components/schemas/StyleProfileSummary"},"example":[]}}},"example":{"styles":[]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"post":{"operationId":"analyzeStyle","summary":"Analyze writing style from recent tweets","tags":["Composition"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"X username whose recent tweets define the style.","content":{"application/json":{"schema":{"type":"object","required":["username"],"properties":{"username":{"type":"string","description":"X username to analyze","example":"elonmusk"}}},"example":{"username":"elonmusk"}}}},"responses":{"200":{"description":"Fresh cached style profile returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StyleProfile"},"example":{"xUsername":"elonmusk","tweetCount":50,"isOwnAccount":true,"fetchedAt":"2025-01-15T12:00:00Z","tweets":[{"id":"1234567890","text":"Just launched our new feature!"}]}}}},"201":{"description":"Style profile created or refreshed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StyleProfile"},"example":{"xUsername":"elonmusk","tweetCount":50,"isOwnAccount":true,"fetchedAt":"2025-01-15T12:00:00Z","tweets":[{"id":"1234567890","text":"Just launched our new feature!"}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/styles/compare":{"get":{"operationId":"compareStyles","summary":"Compare two style profiles","tags":["Composition"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"username1","in":"query","required":true,"schema":{"type":"string"},"description":"First username to compare"},{"name":"username2","in":"query","required":true,"schema":{"type":"string"},"description":"Second username to compare"}],"responses":{"200":{"description":"Style comparison","content":{"application/json":{"schema":{"type":"object","required":["style1","style2"],"properties":{"style1":{"$ref":"#/components/schemas/StyleProfile"},"style2":{"$ref":"#/components/schemas/StyleProfile"}}},"example":{"style1":{"xUsername":"elonmusk","tweetCount":50,"isOwnAccount":true,"fetchedAt":"2025-01-15T12:00:00Z","tweets":[{"id":"1234567890","text":"Just launched our new feature!"}]},"style2":{"xUsername":"BillGates","tweetCount":40,"isOwnAccount":false,"fetchedAt":"2025-01-15T12:00:00Z","tweets":[{"id":"9876543210","text":"Climate change is a global challenge."}]}}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/styles/{id}":{"get":{"operationId":"getStyle","summary":"Get cached style profile","tags":["Composition"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/StyleId"}],"responses":{"200":{"description":"Style profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StyleProfile"},"example":{"xUsername":"elonmusk","tweetCount":50,"isOwnAccount":true,"fetchedAt":"2025-01-15T12:00:00Z","tweets":[{"id":"1234567890","text":"Just launched our new feature!"}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"put":{"operationId":"saveStyle","summary":"Save style profile with custom tweets","tags":["Composition"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/StyleId"}],"requestBody":{"required":true,"description":"Label and sample tweets that define the style profile.","content":{"application/json":{"schema":{"type":"object","required":["label","tweets"],"properties":{"label":{"type":"string","description":"Display label for the style","example":"Professional Voice"},"tweets":{"type":"array","items":{"type":"object","required":["text"],"properties":{"text":{"type":"string","example":"Excited to share our latest research findings."}}},"description":"Array of tweet objects","example":[{"text":"Excited to share our latest research findings."}]}}},"example":{"label":"Professional Voice","tweets":[{"text":"Excited to share our latest research findings."}]}}}},"responses":{"200":{"description":"Style profile saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StyleProfile"},"example":{"xUsername":"elonmusk","tweetCount":1,"isOwnAccount":true,"fetchedAt":"2025-01-15T12:00:00Z","tweets":[{"id":"1234567890","text":"Excited to share our latest research findings."}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"delete":{"operationId":"deleteStyle","summary":"Delete a style profile","tags":["Composition"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/StyleId"}],"responses":{"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/styles/{id}/performance":{"get":{"operationId":"getStylePerformance","summary":"Get engagement metrics for style tweets","tags":["Composition"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/StyleId"}],"responses":{"200":{"description":"Performance metrics","content":{"application/json":{"schema":{"type":"object","required":["xUsername","tweetCount","tweets"],"properties":{"xUsername":{"type":"string","example":"elonmusk"},"tweetCount":{"type":"integer","example":5},"tweets":{"type":"array","items":{"type":"object","required":["id","text"],"properties":{"id":{"type":"string","example":"1234567890"},"text":{"type":"string","example":"Excited to share our latest research findings."},"likeCount":{"type":"integer","example":120},"retweetCount":{"type":"integer","example":15},"replyCount":{"type":"integer","example":8},"viewCount":{"type":"integer","example":5000},"createdAt":{"type":"string","example":"2025-01-15T12:00:00Z"}}},"example":[{"id":"1234567890","text":"Excited to share our latest research findings.","likeCount":120,"retweetCount":15,"replyCount":8,"viewCount":5000,"createdAt":"2025-01-15T12:00:00Z"}]}}},"example":{"xUsername":"elonmusk","tweetCount":5,"tweets":[{"id":"1234567890","text":"Excited to share our latest research findings.","likeCount":120,"retweetCount":15,"replyCount":8,"viewCount":5000,"createdAt":"2025-01-15T12:00:00Z"}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/radar":{"get":{"operationId":"getRadar","summary":"Get trending topics from curated sources","tags":["Composition"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor for pagination (from prior response nextCursor)."},{"name":"category","in":"query","schema":{"type":"string","enum":["general","tech","dev","science","culture","politics","business","entertainment"]},"description":"Filter by category."},{"name":"hours","in":"query","schema":{"type":"integer","minimum":1,"maximum":72,"default":6},"description":"Lookback window in hours (1-72, default 6)."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Number of items to return (1-100, default 50)."},{"name":"region","in":"query","schema":{"type":"string","default":"global"},"description":"Region filter. Use `global` or a region code such as `US`, `GB`, `TR`, or `ES`."},{"name":"source","in":"query","schema":{"type":"string","enum":["github","google_trends","hacker_news","polymarket","reddit","trustmrr","wikipedia"]},"description":"Source filter. One of: github, google_trends, hacker_news, polymarket, reddit, trustmrr, wikipedia"}],"responses":{"200":{"description":"Radar items","content":{"application/json":{"schema":{"type":"object","required":["hasMore","items"],"properties":{"hasMore":{"type":"boolean","example":false},"items":{"type":"array","items":{"$ref":"#/components/schemas/RadarItem"},"example":[]},"nextCursor":{"type":"string","description":"Opaque cursor for the next page (present only when hasMore is true).","example":"eyJ0IjoxNzM5OTcyODAwLCJpIjoiOTk5In0="}}},"example":{"hasMore":false,"items":[]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/monitors":{"get":{"operationId":"listMonitors","summary":"List monitors","tags":["Monitors"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"responses":{"200":{"description":"Monitor list","content":{"application/json":{"schema":{"type":"object","required":["monitors","total"],"properties":{"monitors":{"type":"array","items":{"$ref":"#/components/schemas/Monitor"},"example":[]},"total":{"type":"integer","example":0}}},"example":{"monitors":[],"total":0}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"post":{"operationId":"createMonitor","summary":"Create monitor","description":"Creates an instant monitor. Monitors are unlimited. Active monitors check every 1 second and cost 21 credits per hour. Events and webhook deliveries are included. Creation requires available credits for the first hourly charge and username lookup.","tags":["Monitors"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"Target X username and event types to monitor.","content":{"application/json":{"schema":{"type":"object","required":["username","eventTypes"],"properties":{"username":{"type":"string","description":"X username (without @)","example":"elonmusk"},"eventTypes":{"$ref":"#/components/schemas/EventTypeArray","example":["tweet.new","tweet.reply"]}}},"example":{"username":"elonmusk","eventTypes":["tweet.new","tweet.reply"]}}}},"responses":{"201":{"description":"Monitor created","content":{"application/json":{"schema":{"type":"object","required":["id","username","xUserId","eventTypes","isActive","createdAt","nextBillingAt"],"properties":{"id":{"type":"string","example":"42"},"username":{"type":"string","example":"elonmusk"},"xUserId":{"type":"string","example":"1234567890"},"eventTypes":{"$ref":"#/components/schemas/EventTypeArray","example":["tweet.new","tweet.reply"]},"isActive":{"type":"boolean","example":true},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"},"nextBillingAt":{"type":"string","format":"date-time","description":"Next hourly credit charge time. New active monitors are due immediately.","example":"2025-01-15T12:00:00Z"}}},"example":{"id":"42","username":"elonmusk","xUserId":"1234567890","eventTypes":["tweet.new","tweet.reply"],"isActive":true,"createdAt":"2025-01-15T12:00:00Z","nextBillingAt":"2025-01-15T12:00:00Z"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"X user not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"user_not_found","message":"X user not found. Check the username."}}}},"409":{"description":"Monitor already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"monitor_already_exists","message":"Monitor already exists."}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/monitors/keywords":{"get":{"operationId":"listKeywordMonitors","summary":"List keyword monitors","tags":["Monitors"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"responses":{"200":{"description":"Keyword monitor list","content":{"application/json":{"schema":{"type":"object","required":["monitors","total"],"properties":{"monitors":{"type":"array","items":{"$ref":"#/components/schemas/KeywordMonitor"},"example":[]},"total":{"type":"integer","example":0}}},"example":{"monitors":[],"total":0}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"post":{"operationId":"createKeywordMonitor","summary":"Create keyword monitor","description":"Creates an instant keyword monitor. Keyword monitors are unlimited. Active monitors check every 1 second and cost 21 credits per hour. Events and webhook deliveries are included. Creation requires available credits for the first hourly charge.","tags":["Monitors"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"Search query and event types to monitor.","content":{"application/json":{"schema":{"type":"object","required":["query","eventTypes"],"properties":{"query":{"type":"string","minLength":1,"maxLength":512,"description":"X search query to monitor. Whitespace is normalized.","example":"xquik OR \"x api\""},"eventTypes":{"$ref":"#/components/schemas/EventTypeArray","example":["tweet.new"]}}},"example":{"query":"xquik OR \"x api\"","eventTypes":["tweet.new"]}}}},"responses":{"201":{"description":"Keyword monitor created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordMonitor"},"example":{"id":"21","query":"xquik OR \"x api\"","eventTypes":["tweet.new"],"isActive":true,"createdAt":"2025-01-15T12:00:00Z","nextBillingAt":"2025-01-15T12:00:00Z"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"409":{"description":"Keyword monitor already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"monitor_already_exists","message":"Monitor already exists."}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/monitors/keywords/{id}":{"get":{"operationId":"getKeywordMonitor","summary":"Get keyword monitor","tags":["Monitors"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"Keyword monitor details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordMonitor"},"example":{"id":"21","query":"xquik OR \"x api\"","eventTypes":["tweet.new"],"isActive":true,"createdAt":"2025-01-15T12:00:00Z","nextBillingAt":"2025-01-15T13:00:00Z"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"patch":{"operationId":"updateKeywordMonitor","summary":"Update keyword monitor","tags":["Monitors"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"requestBody":{"required":true,"description":"Updated event types or active status.","content":{"application/json":{"schema":{"type":"object","properties":{"eventTypes":{"$ref":"#/components/schemas/EventTypeArray","example":["tweet.new"]},"isActive":{"type":"boolean","example":true}}},"example":{"eventTypes":["tweet.new"],"isActive":true}}}},"responses":{"200":{"description":"Keyword monitor updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordMonitor"},"example":{"id":"21","query":"xquik OR \"x api\"","eventTypes":["tweet.new"],"isActive":true,"createdAt":"2025-01-15T12:00:00Z","nextBillingAt":"2025-01-15T13:00:00Z"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"delete":{"operationId":"deleteKeywordMonitor","summary":"Delete keyword monitor","tags":["Monitors"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/monitors/{id}":{"get":{"operationId":"getMonitor","summary":"Get monitor","tags":["Monitors"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"Monitor details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Monitor"},"example":{"id":"42","username":"elonmusk","xUserId":"1234567890","eventTypes":["tweet.new","tweet.reply"],"isActive":true,"createdAt":"2025-01-15T12:00:00Z","nextBillingAt":"2025-01-15T13:00:00Z"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"patch":{"operationId":"updateMonitor","summary":"Update monitor","tags":["Monitors"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"requestBody":{"required":true,"description":"Event type list or active state for the account monitor.","content":{"application/json":{"schema":{"type":"object","properties":{"eventTypes":{"$ref":"#/components/schemas/EventTypeArray","example":["tweet.new"]},"isActive":{"type":"boolean","example":true}}},"example":{"eventTypes":["tweet.new"],"isActive":true}}}},"responses":{"200":{"description":"Monitor updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Monitor"},"example":{"id":"42","username":"elonmusk","xUserId":"1234567890","eventTypes":["tweet.new"],"isActive":true,"createdAt":"2025-01-15T12:00:00Z","nextBillingAt":"2025-01-15T13:00:00Z"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"delete":{"operationId":"deleteMonitor","summary":"Delete monitor","tags":["Monitors"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/events":{"get":{"operationId":"listEvents","summary":"List events","tags":["Events"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/After"},{"name":"monitorId","in":"query","description":"Filter events by monitor ID","schema":{"type":"string"}},{"name":"eventType","in":"query","description":"Filter events by type","schema":{"$ref":"#/components/schemas/EventType"}}],"responses":{"200":{"description":"Event list","content":{"application/json":{"schema":{"type":"object","required":["events","hasMore"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"},"example":[]},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","example":"abc123"}}},"example":{"events":[],"hasMore":false}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/events/{id}":{"get":{"operationId":"getEvent","summary":"Get event","tags":["Events"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"Event details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventDetail"},"example":{"id":"42","type":"tweet.new","username":"elonmusk","monitorId":"7","monitorType":"account","occurredAt":"2025-01-15T12:00:00Z","data":{"tweetId":"1234567890"}}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/extractions":{"get":{"operationId":"listExtractions","summary":"List extraction jobs","tags":["Extractions"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/After"},{"name":"toolType","in":"query","description":"Filter by extraction tool type","schema":{"$ref":"#/components/schemas/ExtractionToolType"}},{"name":"status","in":"query","description":"Filter by job status","schema":{"type":"string","enum":["running","completed","failed"]}}],"responses":{"200":{"description":"Extraction job list","content":{"application/json":{"schema":{"type":"object","required":["extractions","hasMore"],"properties":{"extractions":{"type":"array","items":{"$ref":"#/components/schemas/ExtractionJob"},"example":[]},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","example":"abc123"}}},"example":{"extractions":[],"hasMore":false}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"post":{"operationId":"createExtraction","summary":"Run extraction","tags":["Extractions"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"Tool type and target identifier (tweet, user, community, list, or search query).","content":{"application/json":{"schema":{"type":"object","required":["toolType"],"properties":{"toolType":{"$ref":"#/components/schemas/ExtractionToolType","example":"follower_explorer"},"targetTweetId":{"type":"string","example":"1234567890"},"targetUsername":{"type":"string","example":"elonmusk"},"targetCommunityId":{"type":"string","description":"Required for community_post_extractor & community_search.","example":"1500000000000000000"},"targetListId":{"type":"string","description":"Required for list_follower_explorer, list_member_extractor & list_post_extractor.","example":"1234567890"},"targetSpaceId":{"type":"string","description":"Required for space_explorer.","example":"1vOGwMdBqpwGB"},"resultsLimit":{"type":"integer","description":"Maximum number of results to extract. When set, the extraction stops after reaching this limit.","example":1000},"searchQuery":{"type":"string","description":"Required for tweet_search_extractor & community_search.","example":"AI trends 2025"},"fromUser":{"type":"string","description":"Filter by author username (tweet_search_extractor)","example":"nasa"},"toUser":{"type":"string","description":"Filter replies sent to a username (tweet_search_extractor)","example":"openai"},"mentioning":{"type":"string","description":"Filter tweets mentioning a username (tweet_search_extractor)","example":"example_user"},"language":{"type":"string","description":"Language code filter (tweet_search_extractor)","example":"en"},"sinceDate":{"type":"string","format":"date","description":"Start date YYYY-MM-DD (tweet_search_extractor)","example":"2025-01-01"},"untilDate":{"type":"string","format":"date","description":"End date YYYY-MM-DD (tweet_search_extractor)","example":"2025-12-31"},"mediaType":{"type":"string","enum":["images","videos","gifs","media","links","none"],"description":"Media type filter (tweet_search_extractor)","example":"images"},"minFaves":{"type":"integer","minimum":0,"description":"Minimum likes threshold (tweet_search_extractor)","example":10},"minRetweets":{"type":"integer","minimum":0,"description":"Minimum retweets threshold (tweet_search_extractor)","example":5},"minReplies":{"type":"integer","minimum":0,"description":"Minimum replies threshold (tweet_search_extractor)","example":3},"minQuotes":{"type":"integer","minimum":0,"description":"Minimum quote count threshold (tweet_search_extractor)","example":2},"verifiedOnly":{"type":"boolean","description":"Only verified authors (tweet_search_extractor)","example":false},"replies":{"type":"string","enum":["include","exclude","only"],"description":"Reply mode (tweet_search_extractor)","example":"include"},"retweets":{"type":"string","enum":["include","exclude","only"],"description":"Retweet mode (tweet_search_extractor)","example":"exclude"},"quotes":{"type":"string","enum":["include","exclude","only"],"description":"Quote mode (tweet_search_extractor)","example":"include"},"exactPhrase":{"type":"string","description":"Exact phrase to match (tweet_search_extractor)","example":"artificial intelligence"},"excludeWords":{"type":"string","description":"Words or quoted phrases to exclude. Separate with spaces, commas, or lines. (tweet_search_extractor)","example":"spam"},"anyWords":{"type":"string","description":"Words or quoted phrases where any one can match. Separate with spaces, commas, or lines. (tweet_search_extractor)","example":"ChatGPT AI model"},"hashtags":{"type":"string","description":"Hashtags separated by spaces, commas, or lines. (tweet_search_extractor)","example":"#AI startups"},"cashtags":{"type":"string","description":"Cashtags separated by spaces, commas, or lines. (tweet_search_extractor)","example":"$TSLA $NVDA"},"url":{"type":"string","description":"URL substring or domain filter (tweet_search_extractor)","example":"example.com"},"conversationId":{"type":"string","description":"Conversation ID filter (tweet_search_extractor)","example":"1234567890"},"inReplyToTweetId":{"type":"string","description":"Only replies to this tweet ID (tweet_search_extractor)","example":"1234567890"},"quotesOfTweetId":{"type":"string","description":"Only quotes of this tweet ID (tweet_search_extractor)","example":"1234567890"},"retweetsOfTweetId":{"type":"string","description":"Only retweets of this tweet ID (tweet_search_extractor)","example":"1234567890"},"listId":{"type":"string","description":"Search within a list ID (tweet_search_extractor)","example":"1234567890"},"place":{"type":"string","description":"Search within a place ID (tweet_search_extractor)","example":"96683cc9126741d1"},"placeCountry":{"type":"string","description":"Search within a country code (tweet_search_extractor)","example":"US"},"pointRadius":{"type":"string","description":"Geo point radius, e.g. -73.99 40.73 25mi (tweet_search_extractor)","example":"-73.99 40.73 25mi"},"boundingBox":{"type":"string","description":"Geo bounding box, e.g. -74.1 40.6 -73.9 40.8 (tweet_search_extractor)","example":"-74.1 40.6 -73.9 40.8"},"advancedQuery":{"type":"string","description":"Raw advanced search query appended as-is (tweet_search_extractor)","example":"min_faves:100"}}},"example":{"toolType":"follower_explorer","targetUsername":"elonmusk"}}}},"responses":{"202":{"description":"Extraction started","content":{"application/json":{"schema":{"type":"object","required":["id","toolType","status"],"properties":{"id":{"type":"string","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"toolType":{"$ref":"#/components/schemas/ExtractionToolType","example":"follower_explorer"},"status":{"type":"string","const":"running","example":"running"}}},"example":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","toolType":"follower_explorer","status":"running"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/extractions/estimate":{"post":{"operationId":"estimateExtraction","summary":"Estimate extraction cost","tags":["Extractions"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"Same parameters as a real extraction; returns estimated credit cost without running the job.","content":{"application/json":{"schema":{"type":"object","required":["toolType"],"properties":{"toolType":{"$ref":"#/components/schemas/ExtractionToolType","example":"follower_explorer"},"targetTweetId":{"type":"string","example":"1234567890"},"targetUsername":{"type":"string","example":"elonmusk"},"targetCommunityId":{"type":"string","description":"Required for community_post_extractor & community_search.","example":"1500000000000000000"},"targetListId":{"type":"string","description":"Required for list_follower_explorer, list_member_extractor & list_post_extractor.","example":"1234567890"},"targetSpaceId":{"type":"string","description":"Required for space_explorer.","example":"1vOGwMdBqpwGB"},"resultsLimit":{"type":"integer","description":"Maximum number of results to estimate. When set, the estimate caps projected results to this value.","example":1000},"searchQuery":{"type":"string","description":"Required for tweet_search_extractor & community_search.","example":"AI trends 2025"},"fromUser":{"type":"string","description":"Estimate only tweets from this author username (tweet_search_extractor)","example":"nasa"},"toUser":{"type":"string","description":"Estimate replies sent to this username (tweet_search_extractor)","example":"openai"},"mentioning":{"type":"string","description":"Estimate tweets mentioning this username (tweet_search_extractor)","example":"example_user"},"language":{"type":"string","description":"Language code used for estimate filtering (tweet_search_extractor)","example":"en"},"sinceDate":{"type":"string","format":"date","description":"Estimate start date in YYYY-MM-DD format (tweet_search_extractor)","example":"2025-01-01"},"untilDate":{"type":"string","format":"date","description":"Estimate end date in YYYY-MM-DD format (tweet_search_extractor)","example":"2025-12-31"},"mediaType":{"type":"string","enum":["images","videos","gifs","media","links","none"],"description":"Media type used for estimate filtering (tweet_search_extractor)","example":"images"},"minFaves":{"type":"integer","minimum":0,"description":"Minimum likes threshold for estimated results (tweet_search_extractor)","example":10},"minRetweets":{"type":"integer","minimum":0,"description":"Minimum retweets threshold for estimated results (tweet_search_extractor)","example":5},"minReplies":{"type":"integer","minimum":0,"description":"Minimum replies threshold for estimated results (tweet_search_extractor)","example":3},"minQuotes":{"type":"integer","minimum":0,"description":"Minimum quote count threshold for estimated results (tweet_search_extractor)","example":2},"verifiedOnly":{"type":"boolean","description":"Estimate only verified authors (tweet_search_extractor)","example":false},"replies":{"type":"string","enum":["include","exclude","only"],"description":"Reply mode used for estimation (tweet_search_extractor)","example":"include"},"retweets":{"type":"string","enum":["include","exclude","only"],"description":"Retweet mode used for estimation (tweet_search_extractor)","example":"exclude"},"quotes":{"type":"string","enum":["include","exclude","only"],"description":"Quote mode used for estimation (tweet_search_extractor)","example":"include"},"exactPhrase":{"type":"string","description":"Exact phrase filter for search estimation","example":"artificial intelligence"},"excludeWords":{"type":"string","description":"Words or quoted phrases excluded from estimated results. Separate with spaces, commas, or lines.","example":"spam"},"anyWords":{"type":"string","description":"Alternative words or quoted phrases for estimated results. Separate with spaces, commas, or lines.","example":"ChatGPT AI model"},"hashtags":{"type":"string","description":"Hashtags applied to the estimate, separated by spaces, commas, or lines.","example":"#AI startups"},"cashtags":{"type":"string","description":"Cashtags applied to the estimate, separated by spaces, commas, or lines.","example":"$TSLA $NVDA"},"url":{"type":"string","description":"URL substring or domain filter used for estimation (tweet_search_extractor)","example":"example.com"},"conversationId":{"type":"string","description":"Conversation ID filter used for estimation (tweet_search_extractor)","example":"1234567890"},"inReplyToTweetId":{"type":"string","description":"Estimate only replies to this tweet ID (tweet_search_extractor)","example":"1234567890"},"quotesOfTweetId":{"type":"string","description":"Estimate only quotes of this tweet ID (tweet_search_extractor)","example":"1234567890"},"retweetsOfTweetId":{"type":"string","description":"Estimate only retweets of this tweet ID (tweet_search_extractor)","example":"1234567890"},"listId":{"type":"string","description":"Estimate search results within this list ID (tweet_search_extractor)","example":"1234567890"},"place":{"type":"string","description":"Estimate search results within this place ID (tweet_search_extractor)","example":"96683cc9126741d1"},"placeCountry":{"type":"string","description":"Estimate search results within this country code (tweet_search_extractor)","example":"US"},"pointRadius":{"type":"string","description":"Geo point radius used for estimation, e.g. -73.99 40.73 25mi (tweet_search_extractor)","example":"-73.99 40.73 25mi"},"boundingBox":{"type":"string","description":"Geo bounding box used for estimation, e.g. -74.1 40.6 -73.9 40.8 (tweet_search_extractor)","example":"-74.1 40.6 -73.9 40.8"},"advancedQuery":{"type":"string","description":"Raw advanced query string appended to the estimate (tweet_search_extractor)","example":"min_faves:100"}}},"example":{"toolType":"follower_explorer","targetUsername":"elonmusk"}}}},"responses":{"200":{"description":"Extraction estimate","content":{"application/json":{"schema":{"type":"object","required":["estimatedResults","creditsRequired","creditsAvailable","allowed","source"],"properties":{"estimatedResults":{"type":"integer","example":500},"creditsRequired":{"type":"string","example":"500"},"creditsAvailable":{"type":"string","example":"50000"},"allowed":{"type":"boolean","example":true},"source":{"type":"string","enum":["followers","following","paginationCap","posts","quoteCount","replyCount","resultsLimit","retweetCount","unknown"],"example":"replyCount"},"resolvedXUserId":{"type":"string","example":"123456"}}},"example":{"estimatedResults":500,"creditsRequired":"500","creditsAvailable":"50000","allowed":true,"source":"replyCount"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/extractions/{id}":{"get":{"operationId":"getExtraction","summary":"Get extraction results","tags":["Extractions"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Extraction public ID (UUID)"},{"name":"limit","in":"query","description":"Maximum number of results to return (1-1000, default 100)","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"$ref":"#/components/parameters/After"}],"responses":{"200":{"description":"Extraction job with results","content":{"application/json":{"schema":{"type":"object","required":["job","results","hasMore"],"properties":{"job":{"type":"object","additionalProperties":true,"x-stainless-any":true,"description":"Extraction job metadata - shape varies by tool type (JSON)","x-stainless-terraform-type":"string","example":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","toolType":"follower_explorer","status":"completed"}},"results":{"type":"array","items":{"type":"object","additionalProperties":true},"example":[]},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","example":"abc123"}}},"example":{"job":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","toolType":"follower_explorer","status":"completed"},"results":[],"hasMore":false}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/extractions/{id}/export":{"get":{"operationId":"exportExtraction","summary":"Export extraction results","tags":["Extractions"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Extraction public ID"},{"name":"format","in":"query","required":true,"description":"Export file format","schema":{"type":"string","enum":["csv","json","md","md-document","pdf","txt","xlsx"]}}],"responses":{"200":{"description":"Exported file","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/draws":{"get":{"operationId":"listDraws","summary":"List draws","tags":["Draws"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/After"}],"responses":{"200":{"description":"Draw list","content":{"application/json":{"schema":{"type":"object","required":["draws","hasMore"],"properties":{"draws":{"type":"array","items":{"$ref":"#/components/schemas/DrawListItem"},"example":[]},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","example":"abc123"}}},"example":{"draws":[],"hasMore":false}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"post":{"operationId":"createDraw","summary":"Run giveaway draw","description":"Runs a giveaway draw from a source tweet. The draw first checks the minimum credits needed to inspect the source tweet and at least one candidate. Remaining credits cap how many replies and retweeters can be inspected before filters and winner selection run.","tags":["Draws"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"Tweet URL, winner count, and optional eligibility filters (retweet, follow, keywords, hashtags, account age).","content":{"application/json":{"schema":{"type":"object","required":["tweetUrl"],"properties":{"tweetUrl":{"type":"string","format":"uri","example":"https://x.com/elonmusk/status/1234567890"},"winnerCount":{"type":"integer","default":1,"example":3},"backupCount":{"type":"integer","example":2},"uniqueAuthorsOnly":{"type":"boolean","example":true},"mustRetweet":{"type":"boolean","example":true},"mustFollowUsername":{"type":"string","example":"elonmusk"},"filterMinFollowers":{"type":"integer","example":50},"filterAccountAgeDays":{"type":"integer","example":30},"filterLanguage":{"type":"string","example":"en"},"requiredHashtags":{"type":"array","items":{"type":"string"},"example":["#giveaway"]},"requiredKeywords":{"type":"array","items":{"type":"string"},"example":["entered"]},"requiredMentions":{"type":"array","items":{"type":"string"},"example":["@elonmusk"]}}},"example":{"tweetUrl":"https://x.com/elonmusk/status/1234567890","winnerCount":3,"mustRetweet":true}}}},"responses":{"201":{"description":"Draw completed","content":{"application/json":{"schema":{"type":"object","required":["id","tweetId","totalEntries","validEntries","winners"],"properties":{"id":{"type":"string","example":"f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345"},"tweetId":{"type":"string","example":"1234567890"},"totalEntries":{"type":"integer","description":"Candidate entries inspected for this draw after the credit-derived cap. This may be lower than the source tweet's full reply count.","example":250},"validEntries":{"type":"integer","description":"Entries from the inspected candidate set that passed all filters. This is not necessarily every valid reply on the source tweet when credits cap inspection.","example":200},"winners":{"type":"array","items":{"$ref":"#/components/schemas/Winner"},"example":[]}}},"example":{"id":"f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345","tweetId":"1234567890","totalEntries":250,"validEntries":200,"winners":[]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"description":"Insufficient usable credits. Draws can fail before execution when the available balance cannot cover the minimum draw cost. A draw can also fail after execution when its final computed cost cannot be deducted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"insufficient_credits","message":"Insufficient credits"}}}},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/draws/{id}":{"get":{"operationId":"getDraw","summary":"Get draw details","tags":["Draws"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/DrawId"}],"responses":{"200":{"description":"Draw with winners","content":{"application/json":{"schema":{"type":"object","required":["draw","winners"],"properties":{"draw":{"$ref":"#/components/schemas/DrawDetail","example":{"id":"f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345","tweetUrl":"https://x.com/elonmusk/status/1234567890","tweetId":"1234567890","tweetText":"Giving away 3 Tesla Model 3s!","tweetAuthorUsername":"elonmusk","status":"completed","totalEntries":250,"validEntries":200,"tweetLikeCount":50000,"tweetRetweetCount":25000,"tweetReplyCount":10000,"tweetQuoteCount":5000,"createdAt":"2025-01-15T12:00:00Z"}},"winners":{"type":"array","items":{"$ref":"#/components/schemas/Winner"},"example":[]}}},"example":{"draw":{"id":"f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345","tweetUrl":"https://x.com/elonmusk/status/1234567890","tweetId":"1234567890","tweetText":"Giving away 3 Tesla Model 3s!","tweetAuthorUsername":"elonmusk","status":"completed","totalEntries":250,"validEntries":200,"tweetLikeCount":50000,"tweetRetweetCount":25000,"tweetReplyCount":10000,"tweetQuoteCount":5000,"createdAt":"2025-01-15T12:00:00Z"},"winners":[]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/draws/{id}/export":{"get":{"operationId":"exportDraw","summary":"Export draw data","tags":["Draws"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/DrawId"},{"name":"format","in":"query","required":true,"description":"Export output format","schema":{"type":"string","enum":["csv","json","md","md-document","pdf","txt","xlsx"]}},{"name":"type","in":"query","schema":{"type":"string","enum":["winners","entries"],"default":"winners"},"description":"Export winners or all entries"}],"responses":{"200":{"description":"Exported draw file","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhooks","tags":["Webhooks"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"responses":{"200":{"description":"Webhook list","content":{"application/json":{"schema":{"type":"object","required":["webhooks"],"properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"},"example":[]}}},"example":{"webhooks":[]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"post":{"operationId":"createWebhook","summary":"Create webhook","tags":["Webhooks"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"HTTPS callback URL and event types to subscribe to.","content":{"application/json":{"schema":{"type":"object","required":["url","eventTypes"],"properties":{"url":{"type":"string","format":"uri","description":"HTTPS URL","example":"https://example.com/webhook"},"eventTypes":{"$ref":"#/components/schemas/EventTypeArray","example":["tweet.new","tweet.reply"]}}},"example":{"url":"https://example.com/webhook","eventTypes":["tweet.new","tweet.reply"]}}}},"responses":{"201":{"description":"Webhook created","content":{"application/json":{"schema":{"type":"object","required":["id","url","secret","eventTypes","createdAt"],"properties":{"id":{"type":"string","example":"42"},"url":{"type":"string","format":"uri","example":"https://example.com/webhook"},"secret":{"type":"string","description":"Plaintext HMAC signing secret returned only at creation.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"},"eventTypes":{"$ref":"#/components/schemas/EventTypeArray","example":["tweet.new","tweet.reply"]},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"}}},"example":{"id":"42","url":"https://example.com/webhook","secret":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2","eventTypes":["tweet.new","tweet.reply"],"createdAt":"2025-01-15T12:00:00Z"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/webhooks/{id}":{"patch":{"operationId":"updateWebhook","summary":"Update webhook","tags":["Webhooks"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"requestBody":{"required":true,"description":"Updated URL, event types, or active status.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://example.com/webhook"},"eventTypes":{"$ref":"#/components/schemas/EventTypeArray","example":["tweet.new"]},"isActive":{"type":"boolean","example":true}}},"example":{"url":"https://example.com/webhook","isActive":true}}}},"responses":{"200":{"description":"Webhook updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"},"example":{"id":"42","url":"https://example.com/webhook","eventTypes":["tweet.new"],"isActive":true,"consecutiveFailures":0,"deliveryStatus":"active","failureHardCap":200,"createdAt":"2025-01-15T12:00:00Z"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"delete":{"operationId":"deleteWebhook","summary":"Deactivate webhook","tags":["Webhooks"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/webhooks/{id}/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"Delivery list","content":{"application/json":{"schema":{"type":"object","required":["deliveries"],"properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"},"example":[]}}},"example":{"deliveries":[]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/webhooks/{id}/test":{"post":{"operationId":"testWebhook","summary":"Test webhook endpoint","tags":["Webhooks"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"Test result","content":{"application/json":{"schema":{"type":"object","required":["success","statusCode"],"properties":{"success":{"type":"boolean","example":true},"statusCode":{"type":"integer","example":200},"error":{"type":"string","example":""}}},"example":{"success":true,"statusCode":200}}}},"400":{"description":"Invalid webhook ID or test delivery failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"webhook_test_failed"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/webhooks/{id}/resume":{"post":{"operationId":"resumeWebhook","summary":"Test and resume webhook endpoint","tags":["Webhooks"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"Webhook resumed after a successful test delivery","content":{"application/json":{"schema":{"type":"object","required":["success","statusCode","webhook"],"properties":{"success":{"type":"boolean","example":true},"statusCode":{"type":"integer","example":200},"webhook":{"$ref":"#/components/schemas/Webhook"}}},"example":{"success":true,"statusCode":200,"webhook":{"id":"42","url":"https://example.com/webhook","eventTypes":["tweet.new"],"isActive":true,"consecutiveFailures":0,"deliveryStatus":"active","failureHardCap":200,"createdAt":"2025-01-15T12:00:00Z"}}}}},"400":{"description":"Webhook test failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Connection timed out","statusCode":0,"success":false}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/x/tweets":{"get":{"operationId":"getBatchTweets","summary":"Get multiple tweets by IDs","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated tweet IDs (max 100)"}],"responses":{"200":{"description":"List of tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"},"example":{"tweets":[{"id":"1234567890","text":"Just launched our new feature!","createdAt":"2025-01-15T12:00:00Z","likeCount":42,"retweetCount":5,"replyCount":3,"quoteCount":1,"viewCount":1500,"bookmarkCount":2,"author":{"id":"9876543210","username":"elonmusk","name":"Elon Musk","verified":true}}],"has_next_page":true,"next_cursor":"DAACCgACGRElMJcAAA"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}},"post":{"operationId":"createTweet","summary":"Create tweet","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"}],"requestBody":{"required":true,"description":"Account and tweet content. Requires text, media, or both.","content":{"application/json":{"schema":{"type":"object","required":["account"],"properties":{"account":{"type":"string","description":"X account (@username or account ID)","example":"@elonmusk"},"text":{"type":"string","description":"Tweet text (optional when media is provided)","example":"Just launched our new feature!"},"reply_to_tweet_id":{"type":"string","example":"1234567890"},"community_id":{"type":"string","example":"1500000000000000000"},"is_note_tweet":{"type":"boolean","example":false},"media":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Array of public media URLs to attach. Supports up to 4 images or exactly 1 MP4 video up to 100 MB. Each URL must be publicly reachable. Attached media adds 2 credits per started MB across all files.","example":["https://example.com/video.mp4"]}}},"example":{"account":"@elonmusk","text":"Just launched our new feature!"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/write-actions/{id}":{"get":{"operationId":"getWriteActionStatus","summary":"Get write action status","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Write action ID returned by a pending write response."}],"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/x/trends":{"get":{"operationId":"getXTrends","summary":"Get trending hashtags and topics from X by region","tags":["Trends"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"offers":[{"amount":"450","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"charge","method":"tempo"}]},"parameters":[{"name":"woeid","in":"query","schema":{"type":"integer","default":1},"description":"Region WOEID (1=Worldwide, 23424977=US, 23424975=UK, 23424969=Turkey)"},{"name":"count","in":"query","description":"Number of trending topics to return (1-50, default 30)","schema":{"type":"integer","default":30,"minimum":1,"maximum":50}}],"responses":{"200":{"description":"List of trending topics","content":{"application/json":{"schema":{"type":"object","required":["trends","count","woeid"],"properties":{"trends":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"#AI"},"description":{"type":"string","example":"Artificial intelligence discussions"},"query":{"type":"string","example":"%23AI"},"rank":{"type":"integer","example":1}}},"example":[{"name":"#AI","description":"Artificial intelligence discussions","query":"%23AI","rank":1}]},"count":{"type":"integer","example":30},"woeid":{"type":"integer","example":1}}},"example":{"trends":[{"name":"#AI","description":"Artificial intelligence discussions","query":"%23AI","rank":1}],"count":30,"woeid":1}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/tweets/search":{"get":{"operationId":"searchTweets","summary":"Search tweets by query, Tweet ID, X status URL, or account date window","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query (keywords,"},{"name":"queryType","in":"query","required":false,"schema":{"type":"string","enum":["Latest","Top"],"default":"Latest"},"description":"Sort order - Latest (chronological) or Top (engagement-ranked)"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor from previous response"},{"name":"sinceTime","in":"query","schema":{"type":"string"},"description":"ISO 8601 timestamp - only return tweets after this time"},{"name":"untilTime","in":"query","schema":{"type":"string"},"description":"ISO 8601 timestamp - only return tweets before this time"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":200},"description":"Max tweets to return (server paginates internally). Omit for single page (~20). This is an upper bound for paid authenticated calls: remaining credits can reduce the returned page size, and zero affordable results returns 402 insufficient_credits.\n"},{"$ref":"#/components/parameters/TweetFilterFromUser"},{"$ref":"#/components/parameters/TweetFilterToUser"},{"$ref":"#/components/parameters/TweetFilterMentioning"},{"$ref":"#/components/parameters/TweetFilterLanguage"},{"$ref":"#/components/parameters/TweetFilterSinceDate"},{"$ref":"#/components/parameters/TweetFilterUntilDate"},{"$ref":"#/components/parameters/TweetFilterMediaType"},{"$ref":"#/components/parameters/TweetFilterMinFaves"},{"$ref":"#/components/parameters/TweetFilterMinRetweets"},{"$ref":"#/components/parameters/TweetFilterMinReplies"},{"$ref":"#/components/parameters/TweetFilterMinQuotes"},{"$ref":"#/components/parameters/TweetFilterVerifiedOnly"},{"$ref":"#/components/parameters/TweetFilterReplies"},{"$ref":"#/components/parameters/TweetFilterRetweets"},{"$ref":"#/components/parameters/TweetFilterQuotes"},{"$ref":"#/components/parameters/TweetFilterExactPhrase"},{"$ref":"#/components/parameters/TweetFilterExcludeWords"},{"$ref":"#/components/parameters/TweetFilterAnyWords"},{"$ref":"#/components/parameters/TweetFilterHashtags"},{"$ref":"#/components/parameters/TweetFilterCashtags"},{"$ref":"#/components/parameters/TweetFilterUrl"},{"$ref":"#/components/parameters/TweetFilterConversationId"},{"$ref":"#/components/parameters/TweetFilterInReplyToTweetId"},{"$ref":"#/components/parameters/TweetFilterQuotesOfTweetId"},{"$ref":"#/components/parameters/TweetFilterRetweetsOfTweetId"},{"$ref":"#/components/parameters/TweetSearchListId"},{"$ref":"#/components/parameters/TweetSearchPlace"},{"$ref":"#/components/parameters/TweetSearchPlaceCountry"},{"$ref":"#/components/parameters/TweetSearchPointRadius"},{"$ref":"#/components/parameters/TweetSearchBoundingBox"},{"$ref":"#/components/parameters/TweetSearchAdvancedQuery"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"},"example":{"tweets":[{"id":"1234567890","text":"Just launched our new feature!","createdAt":"2025-01-15T12:00:00Z","likeCount":42,"retweetCount":5,"replyCount":3,"quoteCount":1,"viewCount":1500,"bookmarkCount":2,"author":{"id":"9876543210","username":"elonmusk","name":"Elon Musk","verified":true}}],"has_next_page":true,"next_cursor":"DAACCgACGRElMJcAAA"}}}},"400":{"description":"Missing query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"missing_query"}}}},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/articles/{tweetId}":{"get":{"operationId":"getArticle","summary":"Get full X Article content with cover image and metadata","description":"Retrieve the full content of an X Article (long-form post) by numeric tweet ID. Returns article_not_found when the tweet is valid but is not an X Article.","tags":["Articles"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"offers":[{"amount":"750","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"charge","method":"tempo"}]},"parameters":[{"name":"tweetId","in":"path","required":true,"schema":{"type":"string"},"description":"Numeric tweet ID of the article, 15-20 digits. If you have a tweet URL, use the final status ID."}],"responses":{"200":{"description":"Article with author","content":{"application/json":{"schema":{"type":"object","required":["article"],"properties":{"article":{"type":"object","properties":{"title":{"type":"string","example":"The Future of AI"},"previewText":{"type":"string","example":"A deep dive into the latest AI trends..."},"coverImageUrl":{"type":"string","example":"https://pbs.twimg.com/media/example.jpg"},"bodyText":{"type":"string","description":"Plain text joined from all article blocks","example":"This is the first paragraph of the article."},"contents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Block type: paragraph, header-one, header-two, header-three, header-four, header-five, header-six, unordered-list-item, ordered-list-item, blockquote, code-block, media, divider","example":"paragraph"},"text":{"type":"string","example":"This is the first paragraph of the article."},"url":{"type":"string","description":"Media URL for media blocks","example":"https://pbs.twimg.com/media/example.jpg"},"previewUrl":{"type":"string","description":"Preview image URL for media blocks","example":"https://pbs.twimg.com/media/example.jpg"},"width":{"type":"integer","example":1200},"height":{"type":"integer","example":675},"inlineStyleRanges":{"type":"array","description":"Inline text formatting ranges","items":{"type":"object","properties":{"offset":{"type":"integer","example":0},"length":{"type":"integer","example":8},"style":{"type":"string","example":"BOLD"}}}}}}},"createdAt":{"type":"string","example":"2025-01-15T12:00:00Z"},"likeCount":{"type":"integer","example":150},"replyCount":{"type":"integer","example":23},"quoteCount":{"type":"integer","example":8},"viewCount":{"type":"integer","example":5000}}},"author":{"$ref":"#/components/schemas/ArticleAuthor"}}},"example":{"article":{"title":"The Future of AI","previewText":"A deep dive into the latest AI trends...","coverImageUrl":"https://pbs.twimg.com/media/example.jpg","contents":[{"type":"paragraph","text":"This is the first paragraph of the article."}],"createdAt":"2025-01-15T12:00:00Z","likeCount":150,"replyCount":23,"quoteCount":8,"viewCount":5000},"author":{"id":"9876543210","name":"Elon Musk","username":"elonmusk","profilePicture":"https://pbs.twimg.com/profile_images/example.jpg"}}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"Article not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"article_not_found","message":"Article not found. Use an X Article tweet ID."}}}},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/tweets/{id}":{"get":{"operationId":"lookupTweet","summary":"Get tweet with full text, author, metrics and media","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"offers":[{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"charge","method":"tempo"}]},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Numeric tweet ID, 15-20 digits"}],"responses":{"200":{"description":"Tweet with author","content":{"application/json":{"schema":{"type":"object","required":["tweet"],"properties":{"tweet":{"$ref":"#/components/schemas/TweetDetail"},"author":{"$ref":"#/components/schemas/TweetAuthor"}}},"example":{"tweet":{"id":"1234567890","text":"Just launched our new feature!","createdAt":"2025-01-15T12:00:00Z","retweetCount":5,"replyCount":3,"likeCount":42,"quoteCount":1,"viewCount":1500,"bookmarkCount":2},"author":{"id":"9876543210","username":"elonmusk","followers":150000000,"verified":true}}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"Tweet not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"tweet_not_found","message":"Tweet not found. Check the tweet ID."}}}},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}},"delete":{"operationId":"deleteTweet","summary":"Delete tweet","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Tweet ID to delete"}],"requestBody":{"required":true,"description":"Account that owns the tweet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XAccountBody"},"example":{"account":"@elonmusk"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/RateLimitedByX"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/tweets/{id}/like":{"post":{"operationId":"likeTweet","summary":"Like tweet","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Tweet ID to like"}],"requestBody":{"required":true,"description":"Account to perform the like.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XAccountBody"},"example":{"account":"@elonmusk"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/RateLimitedByX"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}},"delete":{"operationId":"unlikeTweet","summary":"Unlike tweet","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Tweet ID to unlike"}],"requestBody":{"required":true,"description":"Account that liked the tweet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XAccountBody"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/RateLimitedByX"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/tweets/{id}/retweet":{"post":{"operationId":"retweet","summary":"Retweet","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Tweet ID to retweet"}],"requestBody":{"required":true,"description":"Account to perform the retweet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XAccountBody"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/RateLimitedByX"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}},"delete":{"operationId":"unretweet","summary":"Unretweet","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Tweet ID to unretweet"}],"requestBody":{"required":true,"description":"Account that retweeted the tweet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XAccountBody"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/RateLimitedByX"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/users/batch":{"get":{"operationId":"getBatchUsers","summary":"Look up multiple users by IDs in one call","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated numeric user IDs (1-100 values). Duplicate IDs are ignored while preserving first-seen order."}],"responses":{"200":{"description":"Matched users plus reconciliation metadata for unavailable IDs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchUsers"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/users/search":{"get":{"operationId":"searchUsers","summary":"Search users by name or username","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"User search query"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for user search"}],"responses":{"200":{"description":"User search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/users/{id}":{"get":{"operationId":"getUser","summary":"Get user profile with follower counts and verification","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"offers":[{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"charge","method":"tempo"}]},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"X username (without @) or user ID"}],"responses":{"200":{"description":"User profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfile"},"example":{"id":"9876543210","username":"elonmusk","name":"Elon Musk","description":"CEO of Tesla, SpaceX, and X","followers":150000000,"following":500,"verified":true}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"user_not_found","message":"X user not found. Check the username."}}}},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/users/{id}/follow":{"post":{"operationId":"followUser","summary":"Follow user","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID to follow"}],"requestBody":{"required":true,"description":"Account to perform the follow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XAccountBody"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}},"delete":{"operationId":"unfollowUser","summary":"Unfollow user","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID to unfollow"}],"requestBody":{"required":true,"description":"Account that follows the target user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XAccountBody"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/users/{id}/remove-follower":{"post":{"operationId":"removeFollower","summary":"Remove follower","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID to remove from your followers"}],"requestBody":{"required":true,"description":"Account whose follower list should be updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XAccountBody"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/followers/check":{"get":{"operationId":"checkFollow","summary":"Check if one user follows another","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"offers":[{"amount":"750","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"charge","method":"tempo"}]},"parameters":[{"name":"source","in":"query","required":true,"schema":{"type":"string"},"description":"Source username, @username, or X or Twitter profile URL"},{"name":"target","in":"query","required":true,"schema":{"type":"string"},"description":"Target username, @username, or X or Twitter profile URL"}],"responses":{"200":{"description":"Follow check result","content":{"application/json":{"schema":{"type":"object","required":["isFollowing","isFollowedBy","sourceUsername","targetUsername"],"properties":{"isFollowing":{"type":"boolean","example":true},"isFollowedBy":{"type":"boolean","example":false},"sourceUsername":{"type":"string","example":"elonmusk"},"targetUsername":{"type":"string","example":"jack"}}},"example":{"isFollowing":true,"isFollowedBy":false,"sourceUsername":"elonmusk","targetUsername":"jack"}}}},"400":{"description":"Missing or invalid params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"missing_params"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/dm/{userId}":{"post":{"operationId":"sendDm","summary":"Send direct message","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"Recipient user ID"}],"requestBody":{"required":true,"description":"Account, message text, and an optional media attachment.","content":{"application/json":{"schema":{"type":"object","required":["account","text"],"properties":{"account":{"type":"string","description":"X account (@username or ID) sending the DM","example":"@elonmusk"},"text":{"type":"string","example":"Example text"},"media_ids":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string"},"description":"Optional array containing exactly 1 uploaded media ID.","example":["1234567890123456789"]}}},"example":{"account":"@elonmusk","text":"Example text content","media_ids":["1234567890123456789"]}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/media":{"post":{"operationId":"uploadMedia","summary":"Upload media","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"}],"requestBody":{"required":true,"description":"Upload media with multipart form data, or provide a JSON URL for server-side download.","content":{"multipart/form-data":{"schema":{"type":"object","required":["account","file"],"properties":{"account":{"type":"string","description":"X account (@username or ID) uploading media","example":"@elonmusk"},"file":{"type":"string","format":"binary","description":"Media file to upload","example":"binary-content"},"is_long_video":{"type":"boolean","description":"Set true only for video/mp4 multipart uploads longer than 140 seconds.","example":false}}},"example":{"account":"@elonmusk","file":"file_value","is_long_video":true}},"application/json":{"schema":{"type":"object","required":["account","url"],"properties":{"account":{"type":"string","description":"X account (@username or ID) uploading media from URL","example":"@elonmusk"},"url":{"type":"string","format":"uri","description":"HTTPS URL to download and upload as media","example":"https://example.com/image.png"}}},"example":{"account":"@elonmusk","url":"https://example.com/image.png"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/media/download":{"post":{"operationId":"downloadMedia","summary":"Download images and videos from tweets","tags":["Media"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"Single tweet URL/ID, accepted aliases, or array of up to 50 tweet URLs/IDs for bulk download. When `tweetIds` contains at least one string value, bulk mode is used.","content":{"application/json":{"schema":{"type":"object","properties":{"tweetInput":{"type":"string","description":"Tweet URL or ID (single tweet)","example":"https://x.com/elonmusk/status/1234567890"},"tweetId":{"type":"string","description":"Numeric tweet ID alias for tweetInput","example":"1234567890"},"tweetUrl":{"type":"string","description":"Tweet URL alias for tweetInput","example":"https://x.com/elonmusk/status/1234567890"},"tweetIds":{"type":"array","items":{"type":"string"},"maxItems":50,"description":"Array of tweet URLs or IDs (bulk, max 50 string items)","example":["1234567890","1234567891"]}}},"example":{"tweetInput":"https://x.com/elonmusk/status/1234567890"}}}},"responses":{"200":{"description":"Media download result. Single: tweetId + galleryUrl + cacheHit. Bulk: galleryUrl + totalTweets + totalMedia.","content":{"application/json":{"schema":{"type":"object","properties":{"tweetId":{"type":"string","example":"1234567890"},"galleryUrl":{"type":"string","example":"https://xquik.com/gallery/abc123"},"cacheHit":{"type":"boolean","example":false},"totalTweets":{"type":"integer","example":2},"totalMedia":{"type":"integer","example":5}}},"example":{"tweetId":"1234567890","galleryUrl":"https://xquik.com/gallery/abc123","cacheHit":false}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"Tweet media source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"tweet_not_found","message":"Tweet not found."}}}},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/profile":{"patch":{"operationId":"updateProfile","summary":"Update X profile","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"}],"requestBody":{"required":true,"description":"Account and profile fields to update (name, bio, location, website).","content":{"application/json":{"schema":{"type":"object","required":["account"],"properties":{"account":{"type":"string","description":"X account (@username or ID) to update profile","example":"@elonmusk"},"name":{"type":"string","description":"Display name","example":"Example Name"},"description":{"type":"string","description":"Bio description","example":"CEO of Tesla, SpaceX, and X"},"location":{"type":"string","example":"Austin, TX"},"url":{"type":"string","description":"Website URL","example":"https://x.com"}}},"example":{"account":"@elonmusk","name":"Example Name","description":"description_value","location":"location_value","url":"https://xquik.com/example"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/profile/avatar":{"patch":{"operationId":"updateAvatar","summary":"Update profile avatar","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"}],"requestBody":{"required":true,"description":"Account and avatar image file or HTTPS image URL (max 700 KB).","content":{"multipart/form-data":{"schema":{"type":"object","required":["account","file"],"properties":{"account":{"type":"string","description":"X account (@username or ID) for avatar update","example":"@elonmusk"},"file":{"type":"string","format":"binary","description":"Avatar image (max 700 KB)","example":"binary-content"}}},"example":{"account":"@elonmusk","file":"file_value"}},"application/json":{"schema":{"type":"object","required":["account","url"],"properties":{"account":{"type":"string","description":"X account (@username or ID) receiving avatar from URL","example":"@elonmusk"},"url":{"type":"string","format":"uri","description":"HTTPS URL to the avatar image to download","example":"https://example.com/avatar.png"}}},"example":{"account":"@elonmusk","url":"https://example.com/avatar.png"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/profile/banner":{"patch":{"operationId":"updateBanner","summary":"Update profile banner","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"}],"requestBody":{"required":true,"description":"Account and banner image file or HTTPS image URL (max 2 MB).","content":{"multipart/form-data":{"schema":{"type":"object","required":["account","file"],"properties":{"account":{"type":"string","description":"X account (@username or ID) for banner update","example":"@elonmusk"},"file":{"type":"string","format":"binary","description":"Banner image (max 2MB)","example":"binary-content"}}},"example":{"account":"@elonmusk","file":"file_value"}},"application/json":{"schema":{"type":"object","required":["account","url"],"properties":{"account":{"type":"string","description":"X account (@username or ID) receiving banner from URL","example":"@elonmusk"},"url":{"type":"string","format":"uri","description":"HTTPS URL to the banner image to download","example":"https://example.com/banner.png"}}},"example":{"account":"@elonmusk","url":"https://example.com/banner.png"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/communities":{"post":{"operationId":"createCommunity","summary":"Create community","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"}],"requestBody":{"required":true,"description":"Account, community name, and optional description.","content":{"application/json":{"schema":{"type":"object","required":["account","name"],"properties":{"account":{"type":"string","description":"X account (@username or ID) creating the community","example":"@elonmusk"},"name":{"type":"string","description":"Community name","example":"Example Name"},"description":{"type":"string","description":"Community description","example":"A community for Tesla enthusiasts"}}},"example":{"account":"@elonmusk","name":"Example Name","description":"A community for Tesla enthusiasts"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/communities/{id}":{"delete":{"operationId":"deleteCommunity","summary":"Delete community","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"},{"$ref":"#/components/parameters/ResourceId"}],"requestBody":{"required":true,"description":"Account and community name for deletion confirmation.","content":{"application/json":{"schema":{"type":"object","required":["account","community_name"],"properties":{"account":{"type":"string","description":"X account (@username or ID) deleting the community","example":"@elonmusk"},"community_name":{"type":"string","description":"Community name for confirmation","example":"Tesla Fans"}}},"example":{"account":"@elonmusk","community_name":"Tesla Fans"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/communities/{id}/join":{"post":{"operationId":"joinCommunity","summary":"Join community","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"},{"$ref":"#/components/parameters/ResourceId"}],"requestBody":{"required":true,"description":"Account to join the community.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XAccountBody"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}},"delete":{"operationId":"leaveCommunity","summary":"Leave community","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WriteIdempotencyKey"},{"$ref":"#/components/parameters/ResourceId"}],"requestBody":{"required":true,"description":"Account to leave the community.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XAccountBody"}}}},"responses":{"200":{"$ref":"#/components/responses/WriteActionCompleted"},"202":{"$ref":"#/components/responses/WriteActionAccepted"},"400":{"$ref":"#/components/responses/WriteInvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"409":{"$ref":"#/components/responses/WriteIdempotencyConflict"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/WriteTrackingUnavailable"}}}},"/api/v1/x/accounts":{"get":{"operationId":"listXAccounts","summary":"List connected X accounts","tags":["X Accounts"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"responses":{"200":{"description":"X account list","content":{"application/json":{"schema":{"type":"object","required":["accounts"],"properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/XAccount"},"example":[{"id":"42","xUserId":"9876543210","xUsername":"elonmusk","status":"active","health":"healthy","createdAt":"2025-01-15T12:00:00Z","updatedAt":"2025-03-10T08:30:00Z"}]}}},"example":{"accounts":[{"id":"42","xUserId":"9876543210","xUsername":"elonmusk","status":"active","health":"healthy","createdAt":"2025-01-15T12:00:00Z","updatedAt":"2025-03-10T08:30:00Z"}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"post":{"operationId":"connectXAccount","summary":"Connect X account","tags":["X Accounts"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"X credentials (username, email, password) and optional 2FA secret.","content":{"application/json":{"schema":{"type":"object","required":["username","email","password"],"properties":{"username":{"type":"string","description":"X username","example":"your_x_username"},"email":{"type":"string","description":"Account email","example":"account@example.invalid"},"password":{"type":"string","description":"Account password","example":"<ACCOUNT_PASSWORD>"},"totp_secret":{"type":"string","description":"TOTP secret for 2FA","example":"<TOTP_SECRET>"}}},"example":{"username":"your_x_username","email":"account@example.invalid","password":"<ACCOUNT_PASSWORD>","totp_secret":"<TOTP_SECRET>"}}}},"responses":{"201":{"description":"X account connected after verification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SanitizedXAccount"}}}},"202":{"description":"Additional email verification code required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XAccountConnectionChallenge"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"409":{"$ref":"#/components/responses/ConnectAlreadyConnected"},"422":{"$ref":"#/components/responses/ConnectLoginFailed"},"429":{"$ref":"#/components/responses/ConnectRateLimitExceeded"},"502":{"$ref":"#/components/responses/ConnectUserLookupFailed"},"503":{"$ref":"#/components/responses/ConnectServiceUnavailable"}}}},"/api/v1/x/account-connection-challenges/{id}/submit":{"post":{"operationId":"submitXAccountConnectionChallenge","summary":"Submit X account email verification code","tags":["X Accounts"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"requestBody":{"required":true,"description":"Email verification code requested during account connect.","content":{"application/json":{"schema":{"type":"object","required":["email_code"],"properties":{"email_code":{"type":"string","description":"Code sent to the account email.","example":"<EMAIL_VERIFICATION_CODE>"}}},"example":{"email_code":"<EMAIL_VERIFICATION_CODE>"}}}},"responses":{"201":{"description":"X account connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SanitizedXAccount"}}}},"202":{"description":"Email verification code required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XAccountConnectionChallenge"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/ConnectAlreadyConnected"},"410":{"description":"Verification code expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/ConnectLoginFailed"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/ConnectServiceUnavailable"}}}},"/api/v1/x/accounts/{id}":{"get":{"operationId":"getXAccount","summary":"Get X account details","tags":["X Accounts"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"X account details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XAccountDetail"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"delete":{"operationId":"disconnectXAccount","summary":"Disconnect X account","tags":["X Accounts"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/x/accounts/{id}/reauth":{"post":{"operationId":"reauthXAccount","summary":"Re-authenticate X account","tags":["X Accounts"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"requestBody":{"required":true,"description":"Updated password and optional fields for re-authentication.","content":{"application/json":{"schema":{"type":"object","required":["password"],"properties":{"password":{"type":"string","description":"Updated account password","example":"<ACCOUNT_PASSWORD>"},"totp_secret":{"type":"string","description":"TOTP secret for 2FA re-authentication","example":"<TOTP_SECRET>"},"email":{"type":"string","description":"Email for the X account (updates stored email)","example":"account@example.invalid"}}},"example":{"password":"<ACCOUNT_PASSWORD>","totp_secret":"<TOTP_SECRET>","email":"account@example.invalid"}}}},"responses":{"200":{"description":"Re-authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SanitizedXAccount"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/ReauthAccountNotFound"},"422":{"$ref":"#/components/responses/ConnectLoginFailed"},"429":{"$ref":"#/components/responses/ConnectLoginCooldown"},"503":{"$ref":"#/components/responses/ConnectServiceUnavailable"}}}},"/api/v1/x/accounts/bulk-retry":{"post":{"operationId":"bulkRetryXAccounts","summary":"Bulk retry temporarily failed X accounts","description":"Clears loginFailedAt and loginFailureReason for all accounts with transient or automated failure reasons, making them eligible for retry on next use.\n","tags":["X Accounts"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"responses":{"200":{"description":"Accounts cleared for retry","content":{"application/json":{"schema":{"type":"object","required":["cleared"],"properties":{"cleared":{"type":"integer","description":"Number of accounts cleared","example":3}}},"example":{"cleared":3}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/trends":{"get":{"operationId":"getTrends","summary":"Get trending hashtags and topics by region (alias)","tags":["Trends"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"offers":[{"amount":"450","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"charge","method":"tempo"}]},"parameters":[{"name":"woeid","in":"query","schema":{"type":"integer","default":1},"description":"Region Yahoo WOEID code (1=Worldwide, 23424977=US, 23424975=UK, 23424969=Turkey)"},{"name":"count","in":"query","description":"Number of trending topics returned (1-50, default 30)","schema":{"type":"integer","default":30,"minimum":1,"maximum":50}}],"responses":{"200":{"description":"Trending topics","content":{"application/json":{"schema":{"type":"object","required":["trends","total","woeid"],"properties":{"trends":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"#AI"},"description":{"type":"string","example":"Artificial intelligence discussions"},"query":{"type":"string","example":"%23AI"},"rank":{"type":"integer","example":1}}},"example":[{"name":"#AI","rank":1}]},"total":{"type":"integer","example":30},"woeid":{"type":"integer","example":1}}},"example":{"trends":[{"name":"#AI","description":"Artificial intelligence discussions","query":"%23AI","rank":1}],"total":30,"woeid":1}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/support/attachments/{id}":{"get":{"operationId":"downloadSupportAttachment","summary":"Download support ticket media","description":"Streams an authenticated user's support image or video. Video requests support one standard byte range for seeking and resumable playback.\n","tags":["Support"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Support attachment public ID","example":"att_a1b2c3d4e5f6a1b2c3d4e5f6"},{"name":"Range","in":"header","required":false,"schema":{"type":"string","pattern":"^bytes=(?:[0-9]+-[0-9]*|-[0-9]+)$"},"description":"Optional single byte range","example":"bytes=0-1048575"}],"responses":{"200":{"description":"Complete image or video bytes","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"Requested partial video bytes","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"416":{"description":"Invalid or unsatisfiable byte range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/support/tickets":{"post":{"operationId":"createTicket","summary":"Create a support ticket","tags":["Support"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$ref":"#/components/parameters/SupportIdempotencyKey"}],"requestBody":{"required":true,"description":"Ticket subject and message body.","content":{"application/json":{"schema":{"type":"object","required":["subject","body"],"properties":{"subject":{"type":"string","maxLength":500,"example":"Cannot connect X account"},"body":{"type":"string","maxLength":10000,"title":"TicketContent","example":"I am unable to connect my X account. Please help."}}},"example":{"subject":"Cannot connect X account","body":"I am unable to connect my X account. Please help."}},"multipart/form-data":{"schema":{"type":"object","required":["subject"],"anyOf":[{"required":["body"]},{"required":["attachments"]}],"properties":{"subject":{"type":"string","maxLength":500},"body":{"type":"string","maxLength":10000},"attachments":{"type":"array","maxItems":4,"items":{"type":"string","format":"binary"}}}}}}},"responses":{"200":{"description":"Original ticket replayed after a safe retry","headers":{"Idempotency-Replayed":{"description":"Present as true when replaying the same request.","schema":{"type":"string","const":"true"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/SupportAttachmentReceipt"}}}}}}},"201":{"description":"Ticket created","content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string","example":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/SupportAttachmentReceipt"}}}},"example":{"publicId":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6","attachments":[]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"409":{"description":"Idempotency-Key was reused with different content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"get":{"operationId":"listTickets","summary":"List user's support tickets","tags":["Support"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"responses":{"200":{"description":"List of tickets","content":{"application/json":{"schema":{"type":"object","properties":{"tickets":{"type":"array","items":{"type":"object","properties":{"publicId":{"type":"string","example":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6"},"subject":{"type":"string","example":"Cannot connect X account"},"status":{"type":"string","example":"open"},"messageCount":{"type":"integer","example":2},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"},"updatedAt":{"type":"string","format":"date-time","example":"2025-01-16T09:30:00Z"}}},"example":[{"publicId":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6","subject":"Cannot connect X account","status":"open"}]}}},"example":{"tickets":[{"publicId":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6","subject":"Cannot connect X account","status":"open","messageCount":2,"createdAt":"2025-01-15T12:00:00Z","updatedAt":"2025-01-16T09:30:00Z"}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/support/tickets/{id}":{"get":{"operationId":"getTicket","summary":"Get ticket with all messages","tags":["Support"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Support ticket public ID","example":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6"}],"responses":{"200":{"description":"Ticket detail","content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string","example":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6"},"subject":{"type":"string","example":"Cannot connect X account"},"status":{"type":"string","example":"open"},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"},"updatedAt":{"type":"string","format":"date-time","example":"2025-01-16T09:30:00Z"},"messages":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string","example":"I am unable to connect my X account."},"sender":{"type":"string","example":"user"},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/SupportAttachment"}}}},"example":[{"body":"I am unable to connect my X account.","sender":"user","createdAt":"2025-01-15T12:00:00Z","attachments":[]}]}}},"example":{"publicId":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6","subject":"Cannot connect X account","status":"open","messages":[{"body":"I am unable to connect my X account.","sender":"user","createdAt":"2025-01-15T12:00:00Z","attachments":[]}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"patch":{"operationId":"updateTicketStatus","summary":"Update ticket status","tags":["Support"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Support ticket public ID to update","example":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6"}],"requestBody":{"required":true,"description":"New ticket status (open, resolved, or closed).","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["open","resolved","closed"],"example":"resolved"}}},"example":{"status":"resolved"}}}},"responses":{"200":{"description":"Status updated","content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string","example":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6"},"status":{"type":"string","example":"resolved"}}},"example":{"publicId":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6","status":"resolved"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/support/tickets/{id}/messages":{"post":{"operationId":"addTicketMessage","summary":"Reply to a support ticket","tags":["Support"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Support ticket public ID for the reply","example":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6"},{"$ref":"#/components/parameters/SupportIdempotencyKey"}],"requestBody":{"required":true,"description":"Reply message body (max 10,000 characters).","content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":10000,"title":"MessageContent","example":"Thank you for the update."}}},"example":{"body":"Thank you for the update."}},"multipart/form-data":{"schema":{"type":"object","anyOf":[{"required":["body"]},{"required":["attachments"]}],"properties":{"body":{"type":"string","maxLength":10000},"attachments":{"type":"array","maxItems":4,"items":{"type":"string","format":"binary"}}}}}}},"responses":{"200":{"description":"Original message replayed after a safe retry","headers":{"Idempotency-Replayed":{"description":"Present as true when replaying the same request.","schema":{"type":"string","const":"true"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/SupportAttachmentReceipt"}}}}}}},"201":{"description":"Message added","content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string","example":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/SupportAttachmentReceipt"}}}},"example":{"publicId":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6","attachments":[]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Idempotency-Key was reused with different content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/guest-wallets":{"post":{"operationId":"createGuestWallet","summary":"Create an accountless prepaid wallet checkout","description":"Create a one-use Stripe-hosted checkout after the user explicitly confirms a $10-$250 USD amount. This request creates no charge by itself. The user opens checkout_url on Stripe. This endpoint returns the paid-read API key without requiring an Xquik account, email, dashboard, or Xquik web page. An idempotent replay returns the same key.\n","tags":["Guest Wallets"],"security":[],"parameters":[{"$ref":"#/components/parameters/GuestIdempotencyKey"}],"requestBody":{"required":true,"description":"Confirmed USD amount in cents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestWalletPurchaseRequest"},"example":{"amount_minor":1000,"currency":"usd"}}}},"responses":{"201":{"description":"Stripe-hosted checkout, guest API key, and API status URL.\n","headers":{"Cache-Control":{"description":"Prevents storage of the secret-bearing response.","schema":{"type":"string","const":"no-store, private"}},"Idempotent-Replayed":{"description":"Present as true when replaying the same request.","schema":{"type":"string","const":"true"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestWalletCreateResponse"},"example":{"account_required":false,"amount":{"amount_minor":1000,"currency":"usd"},"api_key":"xq_example_returned_once","authorization":{"header":"Authorization","scheme":"Bearer"},"checkout_url":"https://buy.stripe.com/example","credential_notice":"Store api_key and the Idempotency-Key securely before sharing checkout_url. No email recovery is available.","credits":"66666","expires_at":"2026-07-13T13:00:00.000Z","instructions":"Give checkout_url to the user. They must complete payment on Stripe. Never submit payment for them. After payment, poll status_url every poll_after_seconds until latest_purchase.status is no longer pending.","poll_after_seconds":2,"purchase_id":"gp_example","requires_user_interaction":true,"status":"pending","status_url":"https://xquik.com/api/v1/guest-wallets/status","wallet_id":"gw_example"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"409":{"description":"Idempotency-Key was reused with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Checkout expired or can no longer be used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"Guest wallet is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"description":"Guest wallet checkout is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/guest-wallets/topups":{"post":{"operationId":"topUpGuestWallet","summary":"Create another guest wallet checkout","description":"Create a one-use Stripe-hosted checkout for an existing paid-read guest key after the user explicitly confirms a $10-$250 USD amount. The key remains the same. This request creates no charge by itself and never redirects through an Xquik web page.\n","tags":["Guest Wallets"],"security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/GuestIdempotencyKey"}],"requestBody":{"required":true,"description":"Confirmed USD amount in cents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestWalletPurchaseRequest"},"example":{"amount_minor":1000,"currency":"usd"}}}},"responses":{"201":{"description":"Stripe-hosted checkout and API status URL.","headers":{"Cache-Control":{"description":"Prevents storage of the secret-bearing response.","schema":{"type":"string","const":"no-store, private"}},"Idempotent-Replayed":{"description":"Present as true when replaying the same request.","schema":{"type":"string","const":"true"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestWalletTopupResponse"},"example":{"account_required":false,"amount":{"amount_minor":1000,"currency":"usd"},"checkout_url":"https://buy.stripe.com/example","credits":"66666","expires_at":"2026-07-13T13:00:00.000Z","instructions":"Give checkout_url to the user. They must complete payment on Stripe. Never submit payment for them. After payment, poll status_url every poll_after_seconds until latest_purchase.status is no longer pending.","poll_after_seconds":2,"purchase_id":"gp_example","requires_user_interaction":true,"status":"pending","status_url":"https://xquik.com/api/v1/guest-wallets/status","wallet_id":"gw_example"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"409":{"description":"Idempotency-Key was reused with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Checkout expired or can no longer be used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"Guest wallet is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"description":"Guest wallet checkout is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/guest-wallets/status":{"get":{"operationId":"getGuestWalletStatus","summary":"Get guest wallet and payment status","description":"Poll after Stripe payment. Use usable to decide whether paid reads can run. An active wallet can remain usable while a top-up is pending. A new wallet becomes usable only after verified webhook fulfillment. Send the guest key as Authorization: Bearer.\n","tags":["Guest Wallets"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Guest wallet status without exposing the API key.","headers":{"Cache-Control":{"description":"Prevents storage of wallet status.","schema":{"type":"string","const":"no-store, private"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestWalletStatusResponse"},"example":{"balance":"66666","latest_purchase":{"amount":{"amount_minor":1000,"currency":"usd"},"checkout_url":null,"credits":"66666","expires_at":"2026-07-13T13:00:00.000Z","purchase_id":"gp_example","status":"paid"},"poll_after_seconds":null,"scope":"paid_reads","status":"active","top_up":{"method":"POST","path":"/api/v1/guest-wallets/topups"},"usable":true,"wallet_id":"gw_example"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/credits":{"get":{"operationId":"getCredits","summary":"Get credits balance","tags":["Subscribe"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"responses":{"200":{"description":"Credits balance and usage","content":{"application/json":{"schema":{"type":"object","required":["auto_topup_amount_dollars","auto_topup_enabled","auto_topup_threshold","balance","lifetime_purchased","lifetime_used"],"properties":{"auto_topup_amount_dollars":{"type":"number","description":"Configured dollar amount for each automatic top-up.","example":10},"auto_topup_enabled":{"type":"boolean","example":false},"auto_topup_threshold":{"type":"string","description":"Credit balance threshold that triggers automatic top-up when enabled, represented as a bigint string.","example":"50000"},"balance":{"type":"string","description":"Current credit balance as a bigint string to preserve precision above Number.MAX_SAFE_INTEGER.","example":"50000"},"lifetime_purchased":{"type":"string","description":"Lifetime purchased credits as a bigint string.","example":"200000"},"lifetime_used":{"type":"string","description":"Lifetime consumed credits as a bigint string.","example":"150000"}}},"example":{"auto_topup_amount_dollars":10,"auto_topup_enabled":false,"auto_topup_threshold":"50000","balance":"50000","lifetime_purchased":"200000","lifetime_used":"150000"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/credits/topup":{"post":{"operationId":"topUpCredits","summary":"Create credit top-up checkout","description":"Create a Stripe Checkout session only after the user confirms. The request never completes payment or adds credits by itself.\n","tags":["Subscribe"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"Confirmed dollar amount for the credit top-up checkout.","content":{"application/json":{"schema":{"type":"object","required":["dollars"],"properties":{"dollars":{"type":"integer","description":"Amount to top up in US dollars. Minimum 10.","minimum":10,"example":10},"locale":{"type":"string","description":"Optional checkout locale. Defaults to en.","example":"en"}}},"example":{"dollars":10}}}},"responses":{"200":{"description":"Top-up payment links","content":{"application/json":{"schema":{"type":"object","required":["url","redirect_url"],"properties":{"redirect_url":{"type":"string","format":"uri","description":"Stable first-party Xquik redirect URL for the active Stripe Checkout session.","example":"https://xquik.com/api/v1/credits/topup/redirect?session_id=cs_test_123"},"url":{"type":"string","format":"uri","description":"Same stable first-party Xquik redirect URL as redirect_url. The response never exposes a raw Stripe Checkout URL.","example":"https://xquik.com/api/v1/credits/topup/redirect?session_id=cs_test_123"}}},"example":{"redirect_url":"https://xquik.com/api/v1/credits/topup/redirect?session_id=cs_test_123","url":"https://xquik.com/api/v1/credits/topup/redirect?session_id=cs_test_123"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/credits/topup/redirect":{"get":{"operationId":"redirectCreditTopupCheckout","summary":"Redirect to an active top-up payment page","tags":["Subscribe"],"security":[],"parameters":[{"name":"session_id","in":"query","required":true,"schema":{"type":"string"},"description":"Billing session ID returned by the top-up billing flow."}],"responses":{"303":{"description":"Redirects to the active payment page.","headers":{"Location":{"description":"Payment page URL.","schema":{"type":"string","format":"uri"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"description":"Top-up payment session is no longer active."},"502":{"description":"Payment page lookup failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"missing_url"}}}}}}}}},"/api/v1/credits/topup/status":{"get":{"operationId":"getCreditTopupStatus","summary":"Get top-up billing status","tags":["Subscribe"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"session_id","in":"query","required":true,"schema":{"type":"string"},"description":"Billing session ID returned by the top-up billing flow."}],"responses":{"200":{"description":"Top-up billing status","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"amount_dollars":{"anyOf":[{"type":"integer","minimum":10},{"type":"null"}],"description":"Dollar amount requested for the top-up.","example":25},"credits":{"type":"string","description":"Bigint string credit amount granted or pending.","example":"166666"},"status":{"type":"string","enum":["paid","processing","failed","expired"],"example":"paid"}}},"example":{"amount_dollars":25,"credits":"166666","status":"paid"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/credits/quick-topup":{"post":{"operationId":"quickTopUpCredits","summary":"Instantly charge saved card for credits","tags":["Subscribe"],"security":[{"cookieSession":[]}],"requestBody":{"required":true,"description":"Dollar amount to charge the saved payment method.","content":{"application/json":{"schema":{"type":"object","required":["dollars"],"properties":{"dollars":{"type":"number","description":"Dollar amount for the top-up","minimum":10,"maximum":500,"example":25}}},"example":{"dollars":25}}}},"responses":{"200":{"description":"Quick top-up result","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["outcome","balance","credits"],"properties":{"outcome":{"type":"string","const":"charged"},"balance":{"type":"string","description":"Updated credit balance as a bigint string.","example":"1450"},"credits":{"type":"string","description":"Credits added by this top-up as a bigint string.","example":"1000"}}},{"type":"object","required":["outcome","clientSecret"],"properties":{"outcome":{"type":"string","const":"requires_action"},"clientSecret":{"type":"string","description":"Payment client secret for completing authentication.","example":"pi_3abc_secret_xyz"}}},{"type":"object","required":["outcome"],"properties":{"outcome":{"type":"string","const":"no_payment_method"}}}]},"examples":{"charged":{"summary":"Payment succeeded","value":{"outcome":"charged","balance":"1450","credits":"1000"}},"requiresAction":{"summary":"Additional authentication required","value":{"outcome":"requires_action","clientSecret":"pi_3abc_secret_xyz"}},"noPaymentMethod":{"summary":"No saved payment method","value":{"outcome":"no_payment_method"}}}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/v1/x/tweets/{id}/favoriters":{"get":{"operationId":"getTweetFavoriters","summary":"List visible users who liked a tweet","description":"Returns liker profiles that X makes visible for the post. X can withhold liker identities even when the post reports likes. In that case this endpoint returns 424 `favoriters_unavailable` instead of a misleading empty success.\n","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Tweet ID to get favoriters"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for favoriters"},{"$ref":"#/components/parameters/FollowerPageSize"}],"responses":{"200":{"description":"Visible users who liked the tweet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/FavoritersUnavailable"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/users/{id}/tweets":{"get":{"operationId":"getUserTweets","summary":"List recent tweets posted by a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"X user ID or username"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for user tweets"},{"$ref":"#/components/parameters/ResultPageSize"},{"name":"includeReplies","in":"query","schema":{"type":"boolean","default":false},"description":"Include reply tweets"},{"name":"includeParentTweet","in":"query","schema":{"type":"boolean","default":false},"description":"Include parent tweet for replies"},{"$ref":"#/components/parameters/TweetFilterFromUser"},{"$ref":"#/components/parameters/TweetFilterToUser"},{"$ref":"#/components/parameters/TweetFilterMentioning"},{"$ref":"#/components/parameters/TweetFilterLanguage"},{"$ref":"#/components/parameters/TweetFilterSinceDate"},{"$ref":"#/components/parameters/TweetFilterUntilDate"},{"$ref":"#/components/parameters/TweetFilterMediaType"},{"$ref":"#/components/parameters/TweetFilterMinFaves"},{"$ref":"#/components/parameters/TweetFilterMinRetweets"},{"$ref":"#/components/parameters/TweetFilterMinReplies"},{"$ref":"#/components/parameters/TweetFilterMinQuotes"},{"$ref":"#/components/parameters/TweetFilterVerifiedOnly"},{"$ref":"#/components/parameters/TweetFilterReplies"},{"$ref":"#/components/parameters/TweetFilterRetweets"},{"$ref":"#/components/parameters/TweetFilterQuotes"},{"$ref":"#/components/parameters/TweetFilterExactPhrase"},{"$ref":"#/components/parameters/TweetFilterExcludeWords"},{"$ref":"#/components/parameters/TweetFilterAnyWords"},{"$ref":"#/components/parameters/TweetFilterHashtags"},{"$ref":"#/components/parameters/TweetFilterCashtags"},{"$ref":"#/components/parameters/TweetFilterUrl"},{"$ref":"#/components/parameters/TweetFilterConversationId"},{"$ref":"#/components/parameters/TweetFilterInReplyToTweetId"},{"$ref":"#/components/parameters/TweetFilterQuotesOfTweetId"},{"$ref":"#/components/parameters/TweetFilterRetweetsOfTweetId"}],"responses":{"200":{"description":"User tweets list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/users/{id}/replies":{"get":{"operationId":"getUserReplies","summary":"List a user's With Replies timeline","description":"Returns the user's timeline with replies included by default.","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"X user ID or username"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for user replies"},{"$ref":"#/components/parameters/ResultPageSize"},{"name":"includeParentTweet","in":"query","schema":{"type":"boolean","default":false},"description":"Include parent tweet for replies"},{"$ref":"#/components/parameters/TweetFilterFromUser"},{"$ref":"#/components/parameters/TweetFilterToUser"},{"$ref":"#/components/parameters/TweetFilterMentioning"},{"$ref":"#/components/parameters/TweetFilterLanguage"},{"$ref":"#/components/parameters/TweetFilterSinceDate"},{"$ref":"#/components/parameters/TweetFilterUntilDate"},{"$ref":"#/components/parameters/TweetFilterMediaType"},{"$ref":"#/components/parameters/TweetFilterMinFaves"},{"$ref":"#/components/parameters/TweetFilterMinRetweets"},{"$ref":"#/components/parameters/TweetFilterMinReplies"},{"$ref":"#/components/parameters/TweetFilterMinQuotes"},{"$ref":"#/components/parameters/TweetFilterVerifiedOnly"},{"$ref":"#/components/parameters/TweetFilterReplies"},{"$ref":"#/components/parameters/TweetFilterRetweets"},{"$ref":"#/components/parameters/TweetFilterQuotes"},{"$ref":"#/components/parameters/TweetFilterExactPhrase"},{"$ref":"#/components/parameters/TweetFilterExcludeWords"},{"$ref":"#/components/parameters/TweetFilterAnyWords"},{"$ref":"#/components/parameters/TweetFilterHashtags"},{"$ref":"#/components/parameters/TweetFilterCashtags"},{"$ref":"#/components/parameters/TweetFilterUrl"},{"$ref":"#/components/parameters/TweetFilterConversationId"},{"$ref":"#/components/parameters/TweetFilterInReplyToTweetId"},{"$ref":"#/components/parameters/TweetFilterQuotesOfTweetId"},{"$ref":"#/components/parameters/TweetFilterRetweetsOfTweetId"}],"responses":{"200":{"description":"User timeline with replies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/users/{id}/likes":{"get":{"operationId":"getUserLikes","summary":"List tweets liked by a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID or username"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for liked tweets"},{"$ref":"#/components/parameters/ResultPageSize"},{"$ref":"#/components/parameters/TweetFilterFromUser"},{"$ref":"#/components/parameters/TweetFilterToUser"},{"$ref":"#/components/parameters/TweetFilterMentioning"},{"$ref":"#/components/parameters/TweetFilterLanguage"},{"$ref":"#/components/parameters/TweetFilterSinceDate"},{"$ref":"#/components/parameters/TweetFilterUntilDate"},{"$ref":"#/components/parameters/TweetFilterMediaType"},{"$ref":"#/components/parameters/TweetFilterMinFaves"},{"$ref":"#/components/parameters/TweetFilterMinRetweets"},{"$ref":"#/components/parameters/TweetFilterMinReplies"},{"$ref":"#/components/parameters/TweetFilterMinQuotes"},{"$ref":"#/components/parameters/TweetFilterVerifiedOnly"},{"$ref":"#/components/parameters/TweetFilterReplies"},{"$ref":"#/components/parameters/TweetFilterRetweets"},{"$ref":"#/components/parameters/TweetFilterQuotes"},{"$ref":"#/components/parameters/TweetFilterExactPhrase"},{"$ref":"#/components/parameters/TweetFilterExcludeWords"},{"$ref":"#/components/parameters/TweetFilterAnyWords"},{"$ref":"#/components/parameters/TweetFilterHashtags"},{"$ref":"#/components/parameters/TweetFilterCashtags"},{"$ref":"#/components/parameters/TweetFilterUrl"},{"$ref":"#/components/parameters/TweetFilterConversationId"},{"$ref":"#/components/parameters/TweetFilterInReplyToTweetId"},{"$ref":"#/components/parameters/TweetFilterQuotesOfTweetId"},{"$ref":"#/components/parameters/TweetFilterRetweetsOfTweetId"}],"responses":{"200":{"description":"List of liked tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/users/{id}/media":{"get":{"operationId":"getUserMedia","summary":"List media tweets posted by a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID or username for media lookup"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for media tweets"},{"$ref":"#/components/parameters/ResultPageSize"},{"$ref":"#/components/parameters/TweetFilterFromUser"},{"$ref":"#/components/parameters/TweetFilterToUser"},{"$ref":"#/components/parameters/TweetFilterMentioning"},{"$ref":"#/components/parameters/TweetFilterLanguage"},{"$ref":"#/components/parameters/TweetFilterSinceDate"},{"$ref":"#/components/parameters/TweetFilterUntilDate"},{"$ref":"#/components/parameters/TweetFilterMediaType"},{"$ref":"#/components/parameters/TweetFilterMinFaves"},{"$ref":"#/components/parameters/TweetFilterMinRetweets"},{"$ref":"#/components/parameters/TweetFilterMinReplies"},{"$ref":"#/components/parameters/TweetFilterMinQuotes"},{"$ref":"#/components/parameters/TweetFilterVerifiedOnly"},{"$ref":"#/components/parameters/TweetFilterReplies"},{"$ref":"#/components/parameters/TweetFilterRetweets"},{"$ref":"#/components/parameters/TweetFilterQuotes"},{"$ref":"#/components/parameters/TweetFilterExactPhrase"},{"$ref":"#/components/parameters/TweetFilterExcludeWords"},{"$ref":"#/components/parameters/TweetFilterAnyWords"},{"$ref":"#/components/parameters/TweetFilterHashtags"},{"$ref":"#/components/parameters/TweetFilterCashtags"},{"$ref":"#/components/parameters/TweetFilterUrl"},{"$ref":"#/components/parameters/TweetFilterConversationId"},{"$ref":"#/components/parameters/TweetFilterInReplyToTweetId"},{"$ref":"#/components/parameters/TweetFilterQuotesOfTweetId"},{"$ref":"#/components/parameters/TweetFilterRetweetsOfTweetId"}],"responses":{"200":{"description":"List of media tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/users/{id}/followers-you-know":{"get":{"operationId":"getFollowersYouKnow","summary":"List mutual followers between you and a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID for followers-you-know lookup"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for followers-you-know"},{"$ref":"#/components/parameters/FollowerPageSize"}],"responses":{"200":{"description":"List of mutual followers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/bookmarks":{"get":{"operationId":"getBookmarks","summary":"Get bookmarked tweets","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"folderId","in":"query","schema":{"type":"string"},"description":"Optional bookmark folder ID"},{"name":"cursor","in":"query","schema":{"type":"string","example":"DAACCgACGRElMJcAAA"},"description":"Pagination cursor for bookmarks"}],"responses":{"200":{"description":"List of bookmarked tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/bookmarks/folders":{"get":{"operationId":"getBookmarkFolders","summary":"Get bookmark folders","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"responses":{"200":{"description":"List of bookmark folders","content":{"application/json":{"schema":{"type":"object","required":["folders","has_next_page","next_cursor"],"properties":{"folders":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","example":"1234567890"},"name":{"type":"string","example":"Read Later"}}},"example":[{"id":"1234567890","name":"Read Later"}]},"has_next_page":{"type":"boolean","description":"Always false for the current bookmark folder route","example":false},"next_cursor":{"type":"string","description":"Always empty for the current bookmark folder route","example":""}}},"example":{"folders":[{"id":"1234567890","name":"Read Later"}],"has_next_page":false,"next_cursor":""}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/notifications":{"get":{"operationId":"getNotifications","summary":"Get notifications","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["All","Verified","Mentions"],"default":"All"},"description":"Notification type filter. Unrecognized values fall back to All."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for notifications"}],"responses":{"200":{"description":"List of notifications","content":{"application/json":{"schema":{"type":"object","required":["notifications","has_next_page","next_cursor"],"properties":{"notifications":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","example":"1234567890"},"type":{"type":"string","example":"like"},"message":{"type":"string","example":"elonmusk liked your tweet"},"timestamp":{"type":"string","example":"2025-01-15T12:00:00Z"}}},"example":[{"id":"1234567890","type":"like","message":"elonmusk liked your tweet","timestamp":"2025-01-15T12:00:00Z"}]},"has_next_page":{"type":"boolean","example":true},"next_cursor":{"type":"string","example":"DAACCgACGRElMJcAAA"}}},"example":{"notifications":[{"id":"1234567890","type":"like","message":"elonmusk liked your tweet","timestamp":"2025-01-15T12:00:00Z"}],"has_next_page":true,"next_cursor":"DAACCgACGRElMJcAAA"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/timeline":{"get":{"operationId":"getTimeline","summary":"Get home timeline","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"seenTweetIds","in":"query","schema":{"type":"string"},"description":"Comma-separated tweet IDs to exclude from results. Empty entries are ignored."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for timeline"}],"responses":{"200":{"description":"List of timeline tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/dm/{userId}/history":{"get":{"operationId":"getDmHistory","summary":"Get DM conversation history","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"Target user ID"},{"name":"account","in":"query","required":true,"schema":{"type":"string"},"description":"X handle (without the `@` prefix) of the connected X account used to read the conversation. The account must be a participant in the conversation.\n"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for DM history"},{"name":"maxId","in":"query","schema":{"type":"string"},"description":"Legacy pagination cursor (backward compat)"}],"responses":{"200":{"description":"List of DM messages","content":{"application/json":{"schema":{"type":"object","required":["messages","has_next_page","next_cursor"],"properties":{"messages":{"type":"array","items":{"type":"object","required":["id","senderId","receiverId"],"properties":{"id":{"type":"string","example":"1234567890123456789"},"text":{"type":"string","example":"Hey, how are you?"},"senderId":{"type":"string","example":"9876543210"},"receiverId":{"type":"string","example":"1234567890"},"createdAt":{"type":"string","example":"2025-01-15T12:00:00Z"},"mediaUrl":{"type":"string","example":"https://pbs.twimg.com/dm_media/abc.jpg","description":"URL of attached media (image, GIF, or video). Omitted when the message has no media attachment.\n"}}},"example":[{"id":"1234567890123456789","text":"Hey, how are you?","senderId":"9876543210","receiverId":"1234567890"}]},"has_next_page":{"type":"boolean","example":true},"next_cursor":{"type":"string","example":"DAACCgACGRElMJcAAA"}}},"example":{"messages":[{"id":"1234567890123456789","text":"Hey, how are you?","senderId":"9876543210","receiverId":"1234567890"}],"has_next_page":true,"next_cursor":"DAACCgACGRElMJcAAA"}}}},"400":{"description":"Invalid input. Either `invalid_user_id` (path user ID is empty or invalid) or `account_required` (the `account` query parameter was missing or empty).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidUserId":{"summary":"Invalid user ID","value":{"error":"invalid_user_id"}},"accountRequired":{"summary":"Account query parameter missing","value":{"error":"account_required","message":"Provide ?account=<x_handle> for a connected X account. DM history requires a connected participant account."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"DM read forbidden. Either the connected account is not a participant in this conversation (`dm_not_permitted`), the account is suspended, locked, or otherwise restricted (`account_restricted`), or the account session needs to be re-authenticated (`account_needs_reauth`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"dmNotPermitted":{"summary":"Account is not a conversation participant","value":{"error":"dm_not_permitted","message":"X rejected the DM read. The connected account is not a participant in this conversation, or it needs reauthentication. Reconnect the account on the dashboard and try again."}},"accountRestricted":{"summary":"Connected account is restricted","value":{"error":"account_restricted"}},"accountNeedsReauth":{"summary":"Connected account needs reauthentication","value":{"error":"account_needs_reauth"}}}}}},"404":{"description":"Connected X account not found for the authenticated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"account_not_found","message":"X account not found. Connect it first at /dashboard/account?tab=x-accounts."}}}},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/communities/{id}/info":{"get":{"operationId":"getCommunityInfo","summary":"Get community name, description and member count","tags":["Communities"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"offers":[{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"charge","method":"tempo"}]},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Community ID"}],"responses":{"200":{"description":"Community details","content":{"application/json":{"schema":{"type":"object","required":["community"],"properties":{"community":{"type":"object","description":"Community info object","example":{"id":"1500000000000000000","name":"Tesla Fans"},"properties":{"id":{"type":"string","description":"Unique community identifier"},"name":{"type":"string","description":"Display name of the community"},"description":{"type":"string","description":"About text for the community"},"banner_url":{"type":"string","description":"Community banner image URL"},"created_at":{"type":"string","description":"Community creation timestamp"},"join_policy":{"type":"string","description":"Join policy (open or restricted)"},"invites_policy":{"type":"string","description":"Invitation policy"},"is_member":{"type":"boolean","description":"Whether the authenticated viewer is a member"},"is_nsfw":{"type":"boolean","description":"Whether the community is marked sensitive"},"role":{"type":"string","description":"Authenticated viewer's community role"},"creator":{"type":"object","required":["id","username","verified"],"properties":{"id":{"type":"string"},"username":{"type":"string"},"verified":{"type":"boolean"},"name":{"type":"string"}}},"member_count":{"type":"integer","description":"Total member count"},"moderator_count":{"type":"integer","description":"Total moderator count"},"primary_topic":{"type":"object","description":"Primary topic","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"rules":{"type":"array","description":"Community rules","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}}}},"required":["id"]}}},"example":{"community":{"id":"1500000000000000000","name":"Tesla Fans","description":"A community for Tesla enthusiasts","banner_url":"https://xquik.com/example","created_at":"2025-01-15T12:00:00Z","join_policy":"open","member_count":10000,"moderator_count":5}}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/communities/{id}/members":{"get":{"operationId":"getCommunityMembers","summary":"List members of a community","tags":["Communities"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Community ID for member lookup"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor"},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":20,"maximum":200,"default":20},"description":"Items per page (20-200, default 20). This is an upper bound for paid authenticated calls: remaining credits can reduce the returned page size, and zero affordable results returns 402 insufficient_credits.\n"}],"responses":{"200":{"description":"List of community members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/communities/{id}/moderators":{"get":{"operationId":"getCommunityModerators","summary":"List moderators of a community","tags":["Communities"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Community ID for moderator lookup"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for community moderators"}],"responses":{"200":{"description":"List of community moderators","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/communities/{id}/tweets":{"get":{"operationId":"getCommunityTweets","summary":"List tweets posted in a community","tags":["Communities"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Community ID for tweet lookup"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for community tweets"},{"$ref":"#/components/parameters/ResultPageSize"}],"responses":{"200":{"description":"List of community tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/communities/search":{"get":{"operationId":"searchCommunities","summary":"Search tweets within an X Community by keyword","description":"Returns tweets, not community records. Requires a Community ID.","tags":["Communities"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"communityId","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric ID of the community whose posts to search"},{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query"},{"name":"queryType","in":"query","schema":{"type":"string","enum":["Latest","Top"],"default":"Latest"},"description":"Sort order (Latest or Top)"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for community search"},{"$ref":"#/components/parameters/ResultPageSize"}],"responses":{"200":{"description":"Tweet search results from the selected X Community","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/communities/tweets":{"get":{"operationId":"getAllCommunityTweets","summary":"Search tweets within an X Community","description":"Requires a Community ID and keyword query.","tags":["Communities"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"communityId","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric ID of the community to search"},{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Keyword query within the selected community"},{"name":"queryType","in":"query","schema":{"type":"string","enum":["Latest","Top"],"default":"Latest"},"description":"Sort order for community results (Latest or Top)"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for community results"},{"$ref":"#/components/parameters/ResultPageSize"}],"responses":{"200":{"description":"Paginated matching tweets from the selected community","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/lists/{id}/followers":{"get":{"operationId":"getListFollowers","summary":"List followers of an X List","tags":["Lists"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"List ID"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for list followers"},{"$ref":"#/components/parameters/FollowerPageSize"}],"responses":{"200":{"description":"List of followers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/lists/{id}/members":{"get":{"operationId":"getListMembers","summary":"List members of an X List","tags":["Lists"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"List ID for member lookup"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for list members"},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":20,"maximum":200,"default":20},"description":"Members per page (20-200, default 20)"}],"responses":{"200":{"description":"List of members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/lists/{id}/tweets":{"get":{"operationId":"getListTweets","summary":"List tweets from an X List","tags":["Lists"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"List ID for tweet lookup"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for list tweets"},{"$ref":"#/components/parameters/ResultPageSize"},{"name":"sinceTime","in":"query","schema":{"type":"string"},"description":"Unix timestamp - filter after"},{"name":"untilTime","in":"query","schema":{"type":"string"},"description":"Unix timestamp - filter before"},{"name":"includeReplies","in":"query","schema":{"type":"boolean"},"description":"Include replies (default false)"}],"responses":{"200":{"description":"List tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/tweets/{id}/quotes":{"get":{"operationId":"getTweetQuotes","summary":"List quote tweets of a tweet","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Numeric tweet ID to get quotes, 15-20 digits"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for quote tweets"},{"$ref":"#/components/parameters/ResultPageSize"},{"name":"sinceTime","in":"query","schema":{"type":"string"},"description":"Unix timestamp - return quotes posted after this time"},{"name":"untilTime","in":"query","schema":{"type":"string"},"description":"Unix timestamp - return quotes posted before this time"},{"name":"includeReplies","in":"query","schema":{"type":"boolean"},"description":"Include reply quotes (default false)"},{"$ref":"#/components/parameters/TweetFilterFromUser"},{"$ref":"#/components/parameters/TweetFilterToUser"},{"$ref":"#/components/parameters/TweetFilterMentioning"},{"$ref":"#/components/parameters/TweetFilterLanguage"},{"$ref":"#/components/parameters/TweetFilterSinceDate"},{"$ref":"#/components/parameters/TweetFilterUntilDate"},{"$ref":"#/components/parameters/TweetFilterMediaType"},{"$ref":"#/components/parameters/TweetFilterMinFaves"},{"$ref":"#/components/parameters/TweetFilterMinRetweets"},{"$ref":"#/components/parameters/TweetFilterMinReplies"},{"$ref":"#/components/parameters/TweetFilterMinQuotes"},{"$ref":"#/components/parameters/TweetFilterVerifiedOnly"},{"$ref":"#/components/parameters/TweetFilterReplies"},{"$ref":"#/components/parameters/TweetFilterRetweets"},{"$ref":"#/components/parameters/TweetFilterQuotes"},{"$ref":"#/components/parameters/TweetFilterExactPhrase"},{"$ref":"#/components/parameters/TweetFilterExcludeWords"},{"$ref":"#/components/parameters/TweetFilterAnyWords"},{"$ref":"#/components/parameters/TweetFilterHashtags"},{"$ref":"#/components/parameters/TweetFilterCashtags"},{"$ref":"#/components/parameters/TweetFilterUrl"},{"$ref":"#/components/parameters/TweetFilterConversationId"},{"$ref":"#/components/parameters/TweetFilterInReplyToTweetId"},{"$ref":"#/components/parameters/TweetFilterQuotesOfTweetId"},{"$ref":"#/components/parameters/TweetFilterRetweetsOfTweetId"}],"responses":{"200":{"description":"List of quote tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/tweets/{id}/replies":{"get":{"operationId":"getTweetReplies","summary":"List replies to a tweet","description":"Returns visible replies. For an unfiltered first page, Xquik compares a terminal page with the post's reported reply count. If the page is visibly incomplete, the endpoint returns 424 `replies_incomplete` instead of presenting partial coverage as complete. Use tweet search with a `conversation_id:{id}` query as the broader fallback.\n","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Tweet ID to get replies"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for tweet replies"},{"$ref":"#/components/parameters/ResultPageSize"},{"name":"sinceTime","in":"query","schema":{"type":"string"},"description":"Unix timestamp - return replies posted after this time"},{"name":"untilTime","in":"query","schema":{"type":"string"},"description":"Unix timestamp - return replies posted before this time"},{"$ref":"#/components/parameters/TweetFilterFromUser"},{"$ref":"#/components/parameters/TweetFilterToUser"},{"$ref":"#/components/parameters/TweetFilterMentioning"},{"$ref":"#/components/parameters/TweetFilterLanguage"},{"$ref":"#/components/parameters/TweetFilterSinceDate"},{"$ref":"#/components/parameters/TweetFilterUntilDate"},{"$ref":"#/components/parameters/TweetFilterMediaType"},{"$ref":"#/components/parameters/TweetFilterMinFaves"},{"$ref":"#/components/parameters/TweetFilterMinRetweets"},{"$ref":"#/components/parameters/TweetFilterMinReplies"},{"$ref":"#/components/parameters/TweetFilterMinQuotes"},{"$ref":"#/components/parameters/TweetFilterVerifiedOnly"},{"$ref":"#/components/parameters/TweetFilterReplies"},{"$ref":"#/components/parameters/TweetFilterRetweets"},{"$ref":"#/components/parameters/TweetFilterQuotes"},{"$ref":"#/components/parameters/TweetFilterExactPhrase"},{"$ref":"#/components/parameters/TweetFilterExcludeWords"},{"$ref":"#/components/parameters/TweetFilterAnyWords"},{"$ref":"#/components/parameters/TweetFilterHashtags"},{"$ref":"#/components/parameters/TweetFilterCashtags"},{"$ref":"#/components/parameters/TweetFilterUrl"},{"$ref":"#/components/parameters/TweetFilterConversationId"},{"$ref":"#/components/parameters/TweetFilterInReplyToTweetId"},{"$ref":"#/components/parameters/TweetFilterQuotesOfTweetId"},{"$ref":"#/components/parameters/TweetFilterRetweetsOfTweetId"}],"responses":{"200":{"description":"List of replies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/RepliesIncomplete"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/tweets/{id}/retweeters":{"get":{"operationId":"getTweetRetweeters","summary":"List users who retweeted a tweet","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Tweet ID to get retweeters"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for retweeters"},{"$ref":"#/components/parameters/FollowerPageSize"}],"responses":{"200":{"description":"List of retweeters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/tweets/{id}/thread":{"get":{"operationId":"getTweetThread","summary":"Get full conversation thread for a tweet","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Tweet ID to get thread context"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for thread tweets"},{"$ref":"#/components/parameters/ResultPageSize"}],"responses":{"200":{"description":"Thread tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/users/{id}/followers":{"get":{"operationId":"getUserFollowers","summary":"List followers of a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID or username"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for followers list"},{"name":"after","in":"query","deprecated":true,"schema":{"type":"string"},"description":"Legacy cursor alias. Prefer cursor."},{"$ref":"#/components/parameters/FollowerPageSize"},{"name":"limit","in":"query","deprecated":true,"schema":{"type":"integer"},"description":"Legacy integer page size alias for following lists. Prefer pageSize."}],"responses":{"200":{"description":"List of user followers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/users/{id}/following":{"get":{"operationId":"getUserFollowing","summary":"List accounts a user follows","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID or username for following lookup"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for following list"},{"name":"after","in":"query","deprecated":true,"schema":{"type":"string"},"description":"Legacy cursor alias. Prefer cursor."},{"$ref":"#/components/parameters/FollowerPageSize"},{"name":"limit","in":"query","deprecated":true,"schema":{"type":"integer"},"description":"Legacy page size alias. Prefer pageSize."}],"responses":{"200":{"description":"List of following","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/users/{id}/mentions":{"get":{"operationId":"getUserMentions","summary":"List tweets mentioning a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID or username for mentions lookup"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for mentions"},{"$ref":"#/components/parameters/ResultPageSize"},{"name":"sinceTime","in":"query","schema":{"type":"string"},"description":"Unix timestamp - return mentions after this time"},{"name":"untilTime","in":"query","schema":{"type":"string"},"description":"Unix timestamp - return mentions before this time"},{"$ref":"#/components/parameters/TweetFilterFromUser"},{"$ref":"#/components/parameters/TweetFilterToUser"},{"$ref":"#/components/parameters/TweetFilterMentioning"},{"$ref":"#/components/parameters/TweetFilterLanguage"},{"$ref":"#/components/parameters/TweetFilterSinceDate"},{"$ref":"#/components/parameters/TweetFilterUntilDate"},{"$ref":"#/components/parameters/TweetFilterMediaType"},{"$ref":"#/components/parameters/TweetFilterMinFaves"},{"$ref":"#/components/parameters/TweetFilterMinRetweets"},{"$ref":"#/components/parameters/TweetFilterMinReplies"},{"$ref":"#/components/parameters/TweetFilterMinQuotes"},{"$ref":"#/components/parameters/TweetFilterVerifiedOnly"},{"$ref":"#/components/parameters/TweetFilterReplies"},{"$ref":"#/components/parameters/TweetFilterRetweets"},{"$ref":"#/components/parameters/TweetFilterQuotes"},{"$ref":"#/components/parameters/TweetFilterExactPhrase"},{"$ref":"#/components/parameters/TweetFilterExcludeWords"},{"$ref":"#/components/parameters/TweetFilterAnyWords"},{"$ref":"#/components/parameters/TweetFilterHashtags"},{"$ref":"#/components/parameters/TweetFilterCashtags"},{"$ref":"#/components/parameters/TweetFilterUrl"},{"$ref":"#/components/parameters/TweetFilterConversationId"},{"$ref":"#/components/parameters/TweetFilterInReplyToTweetId"},{"$ref":"#/components/parameters/TweetFilterQuotesOfTweetId"},{"$ref":"#/components/parameters/TweetFilterRetweetsOfTweetId"}],"responses":{"200":{"description":"List of mentions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}},"/api/v1/x/users/{id}/verified-followers":{"get":{"operationId":"getUserVerifiedFollowers","summary":"List verified followers of a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID or username for verified followers"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for verified followers"},{"$ref":"#/components/parameters/FollowerPageSize"}],"responses":{"200":{"description":"List of verified followers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/AnonymousGuestAuthenticationRequired"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"$ref":"#/components/responses/XApiError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"$ref":"#/components/responses/XApiError"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Xquik API key passed through the x-api-key header. Xquik-Api-Key is a vendor-prefixed alias. API keys beginning with xq_ can also use Authorization: Bearer."},"oauthBearer":{"type":"http","scheme":"bearer","description":"OAuth 2.1 access token passed through Authorization: Bearer. Values beginning with xq_ remain Xquik API-key credentials, not OAuth tokens."},"cookieSession":{"type":"apiKey","in":"cookie","name":"__Host-xquik_session","description":"Secure Xquik browser session cookie."}},"parameters":{"WriteIdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Generate one unique value for each intended write. Reuse it only when retrying the exact same account, action, target, and payload. A reused key returns the original action. Reusing it with different input returns 409. Replay protection remains active for at least 90 days.\n","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[!-~]{1,255}$"}},"SupportIdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Generate one random value per ticket or reply. Reuse it only when retrying identical text and attachments. Never log this value.\n","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"}},"GuestIdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Generate a cryptographically random UUID v4. Reuse it only to retry the same wallet and amount request. Initial wallet creation can recover the API key from this value, so store it as a secret and never log it.\n","schema":{"type":"string","minLength":36,"maxLength":36,"pattern":"^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$"}},"ResourceId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID returned by the matching create or list endpoint."},"DrawId":{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345"},"description":"Draw public ID returned by create and list draw responses."},"Limit":{"name":"limit","in":"query","description":"Maximum number of items to return (1-100, default 50). For paid per-result endpoints, the returned count may be lower when remaining credits cannot cover the requested page. If zero paid results are affordable, the endpoint returns 402 insufficient_credits.\n","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"ResultPageSize":{"name":"pageSize","in":"query","description":"Maximum items requested from this page (1-100, default 20). The response can contain fewer items because the source returned fewer, filters removed items, or remaining credits cover fewer results. Keep requesting next_cursor while has_next_page is true, even when a page is empty. The deprecated limit and count aliases remain accepted.\n","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},"FollowerPageSize":{"name":"pageSize","in":"query","description":"Maximum user profiles requested from this page (20-200, default 200). The response can contain fewer profiles because the source returned fewer or remaining credits cover fewer results. Keep requesting next_cursor while has_next_page is true. The deprecated limit and count aliases remain accepted.\n","schema":{"type":"integer","minimum":20,"maximum":200,"default":200}},"After":{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor for keyset pagination from prior response next_cursor"},"StyleId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Style profile ID or X username"},"TweetFilterFromUser":{"name":"fromUser","in":"query","schema":{"type":"string"},"description":"Filter by author username."},"TweetFilterToUser":{"name":"toUser","in":"query","schema":{"type":"string"},"description":"Filter replies sent to a username."},"TweetFilterMentioning":{"name":"mentioning","in":"query","schema":{"type":"string"},"description":"Filter tweets mentioning a username."},"TweetFilterLanguage":{"name":"language","in":"query","schema":{"type":"string"},"description":"Language code filter, e.g. en or tr."},"TweetFilterSinceDate":{"name":"sinceDate","in":"query","schema":{"type":"string","format":"date"},"description":"Start date in YYYY-MM-DD format."},"TweetFilterUntilDate":{"name":"untilDate","in":"query","schema":{"type":"string","format":"date"},"description":"End date in YYYY-MM-DD format."},"TweetFilterMediaType":{"name":"mediaType","in":"query","schema":{"type":"string","enum":["images","videos","gifs","media","links","none"]},"description":"Filter by media type."},"TweetFilterMinFaves":{"name":"minFaves","in":"query","schema":{"type":"integer","minimum":0},"description":"Minimum likes threshold."},"TweetFilterMinRetweets":{"name":"minRetweets","in":"query","schema":{"type":"integer","minimum":0},"description":"Minimum retweets threshold."},"TweetFilterMinReplies":{"name":"minReplies","in":"query","schema":{"type":"integer","minimum":0},"description":"Minimum replies threshold."},"TweetFilterMinQuotes":{"name":"minQuotes","in":"query","schema":{"type":"integer","minimum":0},"description":"Minimum quote count threshold."},"TweetFilterVerifiedOnly":{"name":"verifiedOnly","in":"query","schema":{"type":"boolean"},"description":"Only return tweets from verified authors."},"TweetFilterReplies":{"name":"replies","in":"query","schema":{"type":"string","enum":["include","exclude","only"]},"description":"Reply mode."},"TweetFilterRetweets":{"name":"retweets","in":"query","schema":{"type":"string","enum":["include","exclude","only"]},"description":"Retweet mode."},"TweetFilterQuotes":{"name":"quotes","in":"query","schema":{"type":"string","enum":["include","exclude","only"]},"description":"Quote mode."},"TweetFilterExactPhrase":{"name":"exactPhrase","in":"query","schema":{"type":"string"},"description":"Exact phrase to match."},"TweetFilterExcludeWords":{"name":"excludeWords","in":"query","schema":{"type":"string"},"description":"Words or quoted phrases to exclude. Separate with spaces, commas, or lines."},"TweetFilterAnyWords":{"name":"anyWords","in":"query","schema":{"type":"string"},"description":"Words or quoted phrases where any one can match. Separate with spaces, commas, or lines."},"TweetFilterHashtags":{"name":"hashtags","in":"query","schema":{"type":"string"},"description":"Hashtags separated by spaces, commas, or lines."},"TweetFilterCashtags":{"name":"cashtags","in":"query","schema":{"type":"string"},"description":"Cashtags separated by spaces, commas, or lines."},"TweetFilterUrl":{"name":"url","in":"query","schema":{"type":"string"},"description":"URL substring or domain filter."},"TweetFilterConversationId":{"name":"conversationId","in":"query","schema":{"type":"string"},"description":"Conversation ID filter."},"TweetFilterInReplyToTweetId":{"name":"inReplyToTweetId","in":"query","schema":{"type":"string"},"description":"Only replies to this tweet ID."},"TweetFilterQuotesOfTweetId":{"name":"quotesOfTweetId","in":"query","schema":{"type":"string"},"description":"Only quotes of this tweet ID."},"TweetFilterRetweetsOfTweetId":{"name":"retweetsOfTweetId","in":"query","schema":{"type":"string"},"description":"Only retweets of this tweet ID."},"TweetSearchListId":{"name":"listId","in":"query","schema":{"type":"string"},"description":"Search within a list ID."},"TweetSearchPlace":{"name":"place","in":"query","schema":{"type":"string"},"description":"Search within a place ID."},"TweetSearchPlaceCountry":{"name":"placeCountry","in":"query","schema":{"type":"string"},"description":"Search within a country code."},"TweetSearchPointRadius":{"name":"pointRadius","in":"query","schema":{"type":"string"},"description":"Geo point radius, e.g. -73.99 40.73 25mi."},"TweetSearchBoundingBox":{"name":"boundingBox","in":"query","schema":{"type":"string"},"description":"Geo bounding box, e.g. -74.1 40.6 -73.9 40.8."},"TweetSearchAdvancedQuery":{"name":"advancedQuery","in":"query","schema":{"type":"string"},"description":"Raw advanced search query appended as-is."}},"responses":{"WriteActionCompleted":{"description":"Write reached a terminal state.","headers":{"X-Request-Id":{"required":true,"description":"Correlation ID for support and observability.","schema":{"type":"string"}},"Location":{"description":"Relative URL for the durable action record.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/XWriteAction"},"example":{"object":"x_write_action","id":"12345","writeActionId":"12345","action":"like","status":"success","terminal":true,"retryable":false,"safeToRetry":false,"statusUrl":"/api/v1/x/write-actions/12345","pollAfterMs":null,"charged":true,"chargedCredits":"10","billing":{"status":"charged","charged":true,"plannedCredits":"10","chargedCredits":"10"},"request":{"hash":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","payload":{"tweet_id":"9876543210"}},"account":{"id":"42","username":"example"},"target":{"type":"tweet","id":"9876543210"},"targetId":"9876543210","result":{"type":"state_change","id":"9876543210","state":"liked"},"nextAction":null,"sendDispatched":true,"success":true}}}},"WriteActionAccepted":{"description":"Write was accepted or dispatched. Poll Location after Retry-After. Never submit another write while this action remains nonterminal.\n","headers":{"X-Request-Id":{"required":true,"description":"Correlation ID for this accepted write response.","schema":{"type":"string"}},"Location":{"required":true,"description":"Relative URL for polling the durable action record.","schema":{"type":"string"}},"Retry-After":{"required":true,"description":"Recommended polling delay in seconds.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/XWriteAction"},"example":{"object":"x_write_action","id":"12346","writeActionId":"12346","action":"create_tweet","status":"dispatching","terminal":false,"retryable":false,"safeToRetry":false,"statusUrl":"/api/v1/x/write-actions/12346","pollAfterMs":2000,"charged":false,"chargedCredits":"0","billing":{"status":"pending","charged":false,"plannedCredits":"10","chargedCredits":"0"},"request":{"hash":"abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789","payload":{"text":"Hello from Xquik"}},"account":{"id":"42","username":"example"},"target":null,"targetId":null,"result":null,"nextAction":{"type":"poll","url":"/api/v1/x/write-actions/12346","afterMs":2000},"sendDispatched":true,"success":false}}}},"WriteIdempotencyConflict":{"description":"The idempotency key belongs to a different write request.","headers":{"X-Request-Id":{"required":true,"description":"Correlation ID for this idempotency conflict.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/XWriteActionError"},"example":{"charged":false,"chargedCredits":"0","error":"idempotency_conflict","message":"Idempotency-Key was already used with a different request.","safeToRetry":true,"retryable":false,"success":false,"nextAction":{"type":"retry","requiresNewIdempotencyKey":true}}}}},"WriteInvalidInput":{"description":"The write request is invalid and no action was dispatched.","headers":{"X-Request-Id":{"required":true,"description":"Correlation ID for this invalid write request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/XWriteActionError"},"example":{"error":"invalid_input","message":"Invalid input. Check request fields.","charged":false,"chargedCredits":"0","retryable":false,"safeToRetry":true,"success":false,"nextAction":{"type":"fix_request"}}}}},"WriteTrackingUnavailable":{"description":"Durable tracking or the write service is temporarily unavailable. Inspect safeToRetry before creating another action.\n","headers":{"X-Request-Id":{"required":true,"description":"Correlation ID for this tracking failure.","schema":{"type":"string"}},"Retry-After":{"description":"Recommended retry delay in seconds.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/XWriteActionError"},{"$ref":"#/components/schemas/XWriteAction"}]},"example":{"error":"write_tracking_unavailable","message":"Write tracking unavailable. Try again.","charged":false,"chargedCredits":"0","retryable":true,"safeToRetry":true,"success":false,"nextAction":{"type":"retry"}}}}},"Success":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","const":true,"example":true}}},"example":{"success":true}}}},"NoContent":{"description":"Deleted"},"Unauthenticated":{"description":"Unauthenticated","headers":{"Cache-Control":{"description":"Prevents storage of authentication responses.","schema":{"type":"string","const":"no-store"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string","const":"Bearer realm=\"xquik\""}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthenticated","message":"Authentication required. Provide a valid API key or bearer token."}}}},"AnonymousGuestAuthenticationRequired":{"description":"Authentication required for a non-MPP paid read. The Bearer challenge requests authentication and is not a Payment challenge. Requests without credentials advertise accountless Stripe checkout, but create no checkout. Explicit invalid credentials return the plain error shape. Call an advertised action only after explicit user confirmation.\n","headers":{"Cache-Control":{"description":"Prevents storage of the guest checkout action.","schema":{"type":"string","const":"no-store"}},"WWW-Authenticate":{"description":"Bearer authentication challenge, not a Payment challenge.","schema":{"type":"string","const":"Bearer realm=\"xquik\""}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AnonymousGuestAuthenticationRequired"},{"allOf":[{"$ref":"#/components/schemas/Error"},{"not":{"required":["payment_options"]}}]}]},"example":{"account_required":false,"error":"unauthenticated","message":"Authentication required.","next_step":"Ask the user to confirm a USD amount before creating checkout.","payment_options":{"guest_wallet":{"create_checkout":{"account_required":false,"amount_bounds":{"currency":"usd","maximum_minor":25000,"minimum_minor":1000},"body":{"amount_minor":1000,"currency":"usd"},"creates":"checkout_url","method":"POST","path":"/api/v1/guest-wallets","provider":"stripe","required_headers":{"Idempotency-Key":"<cryptographically random UUID v4>"},"requires_authentication":false,"requires_user_confirmation":true,"requires_user_interaction":true,"response_fields":["checkout_url","api_key","status_url"],"response_url_field":"checkout_url"}}}}}}},"InvalidInput":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_input","message":"Invalid input. Check the request body."}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"Resource not found."}}}},"PaymentRequired":{"description":"Payment required. Fixed-price direct MPP requests return a Machine Payments Protocol problem document and a WWW-Authenticate challenge. Authenticated X data requests return balances and explicit Stripe checkout-creation actions. Guest paid-read keys receive only the accountless guest top-up action. Direct MPP challenges also advertise the Stripe wallet action. Other authenticated endpoints return a legacy error shape. A failed request never creates checkout. Create checkout only after the user confirms a payment option.\n","headers":{"WWW-Authenticate":{"description":"MPP payment challenge for eligible anonymous pay-per-use requests. Authenticated credit or subscription errors omit this header.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/XWritePaymentRequired"},{"$ref":"#/components/schemas/AuthenticatedPaymentRequired"},{"$ref":"#/components/schemas/GuestPaymentRequired"},{"allOf":[{"$ref":"#/components/schemas/Error"},{"not":{"required":["payment_options"]}}]}]},"example":{"balance":"0","dashboard":"/dashboard/account","error":"insufficient_credits","message":"Insufficient credits. Top up or subscribe to continue.","next_step":"Ask the user to confirm a payment option before creating checkout.","payment_options":{"credits":{"create_checkout":{"body":{"dollars":10,"locale":"en"},"creates":"checkout_url","method":"POST","path":"/api/v1/credits/topup","provider":"stripe","requires_authentication":true,"requires_user_confirmation":true,"response_url_field":"url"}},"subscription":{"create_checkout":{"body":{"tier":"starter"},"creates":"checkout_url","method":"POST","path":"/api/v1/subscribe","provider":"stripe","requires_authentication":true,"requires_user_confirmation":true,"response_url_field":"url"}}},"required":"1","top_up_endpoint":"/api/v1/credits/topup","top_up_url":"POST /api/v1/credits/topup"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/MppPaymentRequired"},"example":{"account_required":false,"challengeId":"Opaque MPP challenge identifier","detail":"Payment is required.","hint":"Use a supported wallet with an offer from the WWW-Authenticate header.","status":402,"title":"Payment Required","type":"https://paymentauth.org/problems/payment-required","next_step":"Ask the user to confirm a USD amount before creating checkout.","payment_options":{"guest_wallet":{"create_checkout":{"account_required":false,"amount_bounds":{"currency":"usd","maximum_minor":25000,"minimum_minor":1000},"body":{"amount_minor":1000,"currency":"usd"},"creates":"checkout_url","method":"POST","path":"/api/v1/guest-wallets","provider":"stripe","required_headers":{"Idempotency-Key":"<cryptographically random UUID v4>"},"requires_authentication":false,"requires_user_confirmation":true,"requires_user_interaction":true,"response_fields":["checkout_url","api_key","status_url"],"response_url_field":"checkout_url"}}}}}}},"AccountAuthError":{"description":"The connected X account needs reauthentication or is currently restricted (locked, suspended, or recovering). Returns an error code of `account_needs_reauth` or `account_restricted`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"account_needs_reauth","message":"X account needs re-authentication. Re-add the account."}}}},"XAccountNotFound":{"description":"Connected X account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"account_not_found","message":"X account not found. Connect it first at /dashboard/account?tab=x-accounts."}}}},"WriteError":{"description":"Write operation failed. Possible error codes include x_write_failed, x_write_ambiguous, x_duplicate_action, and x_daily_limit. Inspect the durable action, safeToRetry, and nextAction fields before retrying.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"x_write_failed","message":"Write action failed unexpectedly. Contact support if this persists."}}}},"WriteRejected":{"description":"X rejected the write or the media URL could not be downloaded. Possible codes: `x_content_too_long`, `x_duplicate_action`, `x_account_suspended`, `x_account_protected`, `x_dm_not_allowed`, `x_target_not_found`, `x_account_feature_required`, `x_rejected`, `media_download_failed` (URL fetch path only - body.url not HTTPS, resolves to private IP, file too large, origin error, or timeout).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"x_rejected","message":"X rejected this request. Wait a few minutes and try again."}}}},"RateLimitedByX":{"description":"X throttled the write. Possible codes: `x_rate_limited` (short-term throttle) or `x_daily_limit` (daily cap hit). Back off and retry later. Distinct from Xquik tier-based 429.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"x_rate_limited","message":"Rate limited by X. Wait before retrying."}}}},"WriteRateLimited":{"description":"A write was throttled by Xquik's tier or action limits (`rate_limit_exceeded`) or by X (`x_rate_limited`, `x_daily_limit`). Respect the `Retry-After` header when present, otherwise back off before retrying.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"retryAfter":{"type":"integer","example":60}}}]},"examples":{"xquikLimit":{"summary":"Xquik tier or action limit","value":{"error":"rate_limit_exceeded","message":"Too many requests. Try again later.","retryAfter":60}},"xLimit":{"summary":"X rate limit","value":{"error":"x_rate_limited","message":"Rate limited by X. Wait before retrying."}}}}}},"TransientError":{"description":"A transient upstream issue occurred. Safe to retry with exponential backoff. Returns error code `x_transient_error`.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/XWriteActionError"}]},"example":{"error":"x_transient_error","message":"X is temporarily unavailable. Retry after a short delay."}}}},"XApiError":{"description":"Dependency unavailable, unauthorized, or rate limited. Default v1 returns 502. The best-practice response contract returns 424 for transparent dependency failures.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"x_api_unavailable","message":"X data source temporarily unavailable. Try again later."}}}},"FavoritersUnavailable":{"description":"X reports likes for the post but does not expose the corresponding user identities. Returns error code `favoriters_unavailable`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"favoriters_unavailable","message":"Users who liked this post are unavailable. Use retweeters or replies instead."}}}},"RepliesIncomplete":{"description":"The direct replies page ended before the post's reported reply count. Returns error code `replies_incomplete` so verification workflows do not treat partial coverage as exhaustive.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"replies_incomplete","message":"Replies are incomplete. Use tweet search with a conversation_id filter."}}}},"ConnectAlreadyConnected":{"description":"The specified X account is already connected to this Xquik account. Returns error code `account_already_connected`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"account_already_connected","message":"This X account is already connected."}}}},"ConnectLoginFailed":{"description":"Login could not continue because credentials or account verification require user action. When a cooldown applies, the response includes `retryAfterMs` and a `Retry-After` header in seconds. Returns error code `login_failed` or `passkey_required`.\n","headers":{"Retry-After":{"description":"Cooldown duration in seconds, when retrying must wait.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"login_failed","message":"Login failed. Check credentials and try again.","retryAfterMs":300000}}}},"ConnectLoginCooldown":{"description":"A prior login attempt triggered a cooldown. Response includes `reason`, `retryAfterMs`, and a `Retry-After` header in seconds. Returns error code `login_cooldown`.\n","headers":{"Retry-After":{"description":"Cooldown duration in seconds.","required":true,"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"login_cooldown","message":"Login is temporarily paused","reason":"temporary_issue","retryAfterMs":60000}}}},"ConnectRateLimitExceeded":{"description":"Too many requests. Either the generous connection safety limit was exceeded (`rate_limit_exceeded`, `retryAfter` seconds, `Retry-After: 900` header) or a prior login attempt triggered a cooldown (`login_cooldown`, `reason`, `retryAfterMs`, `Retry-After` header in seconds).\n","headers":{"Retry-After":{"description":"Required wait in seconds.","required":true,"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate_limit_exceeded","message":"Too many requests. Retry later."}}}},"RateLimitExceeded":{"description":"Xquik tier rate limit exceeded. The response includes a `Retry-After` header with the number of seconds to wait before retrying.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"retryAfter":{"type":"integer","example":60}}}]},"example":{"error":"rate_limit_exceeded","message":"Too many requests. Try again later.","retryAfter":60}}}},"ConnectUserLookupFailed":{"description":"The X username could not be resolved. Verify the handle is correct and the account exists. Default v1 returns 502. The best-practice response contract returns 424. Error code: `x_user_lookup_failed`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"x_user_lookup_failed","message":"X username lookup failed. Try again later."}}}},"ConnectServiceUnavailable":{"description":"The X connection service is temporarily unavailable. Retry after a short delay. Returns error code `service_unavailable`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"Service temporarily unavailable. Try again later."}}}},"ReauthAccountNotFound":{"description":"No X account with this ID belongs to the authenticated user. Returns error code `account_not_found`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"account_not_found","message":"X account not found."}}}}},"schemas":{"XWriteActionBilling":{"type":"object","additionalProperties":false,"required":["status","charged","plannedCredits","chargedCredits"],"properties":{"status":{"type":"string","enum":["not_charged","pending","charged","charge_failed","refunded"],"example":"charged"},"charged":{"type":"boolean","example":true},"plannedCredits":{"type":"string","pattern":"^\\d+$","example":"10"},"chargedCredits":{"type":"string","pattern":"^\\d+$","example":"10"}},"description":"plannedCredits is the approved maximum. chargedCredits comes from the settled credit ledger. Pending or failed writes are not charged.\n","example":{"status":"charged","charged":true,"plannedCredits":"10","chargedCredits":"10"}},"XWriteActionAccount":{"type":["object","null"],"description":"Connected account selected for the write.","additionalProperties":false,"required":["id","username"],"properties":{"id":{"type":"string"},"username":{"type":"string"}},"example":{"id":"42","username":"example"}},"XWriteActionTarget":{"type":["object","null"],"description":"Existing X resource targeted by the write, when applicable.","additionalProperties":false,"required":["type","id"],"properties":{"type":{"type":"string","enum":["tweet","user","community"]},"id":{"type":"string"}},"example":{"type":"tweet","id":"9876543210"}},"XWriteActionRequest":{"type":"object","description":"Stable fingerprint and sanitized payload for replay checks.","additionalProperties":false,"required":["hash","payload"],"properties":{"hash":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$","description":"Stable hash of account, action, target, and payload."},"payload":{"type":["object","null"],"additionalProperties":true,"description":"Exact sanitized payload dispatched for this action."}},"example":{"hash":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","payload":{"tweet_id":"9876543210"}}},"XWriteActionResult":{"type":["object","null"],"description":"Confirmed result produced by the write, when available.","additionalProperties":false,"properties":{"type":{"type":"string","enum":["tweet","direct_message","media","community","state_change"]},"id":{"type":"string"},"state":{"type":"string"}},"example":{"type":"state_change","id":"9876543210","state":"liked"}},"XWriteActionNextAction":{"type":["object","null"],"description":"Exact follow-up an API client or agent should perform.","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["poll","retry","verify_result","fix_request"]},"url":{"type":"string"},"afterMs":{"type":"integer","minimum":0},"requiresNewIdempotencyKey":{"type":"boolean"}},"example":{"type":"poll","url":"/api/v1/x/write-actions/12345","afterMs":2000}},"XWriteAction":{"type":"object","required":["object","id","writeActionId","action","status","terminal","retryable","safeToRetry","statusUrl","pollAfterMs","charged","chargedCredits","billing","request","account","target","targetId","result","nextAction","sendDispatched","success"],"properties":{"object":{"type":"string","const":"x_write_action"},"id":{"type":"string","example":"12345"},"writeActionId":{"type":"string","example":"12345"},"action":{"type":"string","example":"like","enum":["create_tweet","delete_tweet","like","unlike","retweet","unretweet","follow","unfollow","remove_follower","send_dm","upload_media","update_profile","update_avatar","update_banner","create_community","delete_community","join_community","leave_community"]},"status":{"type":"string","example":"success","enum":["accepted","dispatching","pending_confirmation","success","failed","expired"]},"terminal":{"type":"boolean","example":true},"retryable":{"type":"boolean","description":"True only when a new attempt can reasonably succeed.","example":false},"safeToRetry":{"type":"boolean","description":"True only when no write was dispatched and a new idempotency key may be used.\n","example":false},"statusUrl":{"type":"string","example":"/api/v1/x/write-actions/12345"},"pollAfterMs":{"type":["integer","null"],"minimum":0,"example":null},"charged":{"type":"boolean","example":true},"chargedCredits":{"type":"string","pattern":"^\\d+$","example":"10"},"billing":{"$ref":"#/components/schemas/XWriteActionBilling"},"request":{"$ref":"#/components/schemas/XWriteActionRequest"},"account":{"$ref":"#/components/schemas/XWriteActionAccount"},"target":{"$ref":"#/components/schemas/XWriteActionTarget"},"targetId":{"type":["string","null"],"example":"9876543210"},"result":{"$ref":"#/components/schemas/XWriteActionResult"},"nextAction":{"$ref":"#/components/schemas/XWriteActionNextAction"},"requestHash":{"type":"string","pattern":"^[0-9a-f]{64}$","example":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"},"requestId":{"type":"string","example":"01JZ8R7QSC9QKT0V7JX4M2A6B8"},"idempotent":{"type":"boolean","example":false},"error":{"type":"string","example":"x_write_ambiguous"},"message":{"type":"string","example":"Invalid input. Check request fields."},"sendDispatched":{"type":"boolean","example":true},"sendDispatchedAt":{"type":"string","format":"date-time","description":"Dispatch timestamp when the write reached execution.","example":"2026-07-21T05:00:00Z"},"createdAt":{"type":"string","format":"date-time","example":"2026-07-21T05:00:00Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-07-21T05:00:02Z"},"completedAt":{"type":"string","format":"date-time","example":"2026-07-21T05:00:02Z"},"expiresAt":{"type":"string","format":"date-time","description":"Deadline for resolving a non-terminal write. This is not the Idempotency-Key retention deadline.\n","example":"2026-07-22T05:00:00Z"},"confirmedAt":{"type":"string","format":"date-time","example":"2026-07-21T05:00:02Z"},"confirmationCheckedAt":{"type":"string","format":"date-time","example":"2026-07-21T05:00:02Z"},"confirmationAttempts":{"type":"integer","minimum":0,"example":1},"tweetId":{"type":"string","description":"Compatibility field for a confirmed tweet result ID.","example":"9876543210"},"messageId":{"type":"string","description":"Compatibility field for a confirmed direct message ID.","example":"1234567890"},"mediaId":{"type":"string","description":"Compatibility field for a confirmed media upload ID.","example":"2345678901"},"mediaUrl":{"type":"string","format":"uri","description":"Public media URL when the upload creates one.","example":"https://media.xquik.com/example.jpg"},"communityId":{"type":"string","description":"Compatibility field for a confirmed community ID.","example":"3456789012"},"communityName":{"type":"string","description":"Confirmed community name when available.","example":"Builders"},"resultId":{"type":"string","description":"Compatibility result ID for other write actions.","example":"9876543210"},"media":{"type":"object","additionalProperties":true,"description":"Media count, kind, size, and billing details when used.","example":{"count":1,"kind":"image"}},"details":{"type":"object","additionalProperties":true,"description":"Structured recovery context for a failed write.","example":{"suggestion":"Poll the action status URL."}},"success":{"type":"boolean","example":true}},"description":"Durable write lifecycle record. Poll statusUrl until terminal is true. Reusing the original Idempotency-Key returns this same record. Submit a new write only when safeToRetry is true, using a new key.\n"},"XWriteActionError":{"type":"object","description":"Canonical pre-dispatch error with safe recovery guidance.","additionalProperties":true,"required":["error","message","retryable","safeToRetry","charged","chargedCredits","success","nextAction"],"properties":{"error":{"type":"string","example":"invalid_input"},"message":{"type":"string","example":"Invalid input. Check request fields."},"retryable":{"type":"boolean","example":false},"safeToRetry":{"type":"boolean","example":true},"charged":{"type":"boolean","const":false},"chargedCredits":{"type":"string","const":"0"},"success":{"type":"boolean","const":false},"writeActionId":{"type":"string","example":"12345"},"statusUrl":{"type":"string","example":"/api/v1/x/write-actions/12345"},"nextAction":{"$ref":"#/components/schemas/XWriteActionNextAction"},"allowedFields":{"type":"array","example":["account","text"],"items":{"type":"string"}},"fieldErrors":{"type":"array","example":[{"code":"required","message":"Account is required.","path":"account"}],"items":{"type":"object","required":["code","message","path"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}}}}}},"XWritePaymentRequired":{"allOf":[{"$ref":"#/components/schemas/XWriteAction"},{"type":"object","required":["error","message"]}],"description":"Durable failed write action with the applicable payment guidance.\n"},"SupportAttachment":{"type":"object","required":["publicId","filename","contentType","kind","sizeBytes","status","url"],"properties":{"publicId":{"type":"string","example":"att_a1b2c3d4e5f6a1b2c3d4e5f6"},"filename":{"type":"string","example":"screen.png"},"contentType":{"type":"string","enum":["image/jpeg","image/png","image/gif","image/webp","video/mp4","video/quicktime","video/webm"]},"kind":{"type":"string","enum":["image","video"]},"sizeBytes":{"type":"integer","format":"int64","example":204800},"status":{"type":"string","enum":["pending","ready","failed"]},"url":{"type":"string","example":"/api/v1/support/attachments/att_a1b2c3d4e5f6a1b2c3d4e5f6"}}},"SupportAttachmentReceipt":{"type":"object","required":["publicId","status"],"properties":{"publicId":{"type":"string","example":"att_a1b2c3d4e5f6a1b2c3d4e5f6"},"status":{"type":"string","enum":["pending","ready","failed"]}}},"PaginatedTweets":{"description":"Paginated tweet results. The item count can be lower than pageSize when the source returns fewer tweets, filters remove tweets, or remaining credits cover fewer results. Follow next_cursor while has_next_page is true. An empty page can still have has_next_page true after filtering. Zero affordable results returns 402 insufficient_credits.\n","type":"object","required":["tweets","has_next_page","next_cursor"],"properties":{"tweets":{"type":"array","items":{"$ref":"#/components/schemas/SearchTweet"},"example":[{"id":"1234567890","text":"Just launched our new feature!","retweetCount":5,"replyCount":3,"likeCount":42,"quoteCount":1,"viewCount":1500,"bookmarkCount":2}]},"has_next_page":{"type":"boolean","example":true},"next_cursor":{"type":"string","example":"DAACCgACGRElMJcAAA"}}},"PaginatedUsers":{"description":"Paginated user profiles. The item count can be lower than pageSize when the source returns fewer profiles or remaining credits cover fewer results. Follow next_cursor while has_next_page is true. A relationship can naturally contain fewer profiles than requested. Zero affordable results returns 402 insufficient_credits.\n","type":"object","required":["users","has_next_page","next_cursor"],"properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/UserProfile"},"example":[{"id":"9876543210","username":"elonmusk","name":"Elon Musk"}]},"has_next_page":{"type":"boolean","example":true},"next_cursor":{"type":"string","example":"DAACCgACGRElMJcAAA"}}},"BatchUsers":{"description":"Batch user lookup results. Duplicate requested IDs are ignored while preserving first-seen order. unavailable_ids identifies processed IDs with no returned profile. unprocessed_ids identifies IDs skipped when available credits limit processing.\n","type":"object","required":["users","has_next_page","next_cursor","requested_count","processed_count","returned_count","unavailable_ids","unprocessed_ids"],"properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/UserProfile"}},"has_next_page":{"type":"boolean","const":false,"description":"Batch lookups never paginate."},"next_cursor":{"type":"string","description":"Empty because batch lookups never paginate.","maxLength":0,"example":""},"requested_count":{"type":"integer","minimum":0,"maximum":100,"description":"Number of unique IDs requested."},"processed_count":{"type":"integer","minimum":0,"maximum":100,"description":"Number of requested IDs included in the lookup."},"returned_count":{"type":"integer","minimum":0,"maximum":100,"description":"Number of user profiles returned and charged."},"unavailable_ids":{"type":"array","description":"Processed IDs with no returned profile, in first-seen request order.","items":{"type":"string","pattern":"^\\d+$"}},"unprocessed_ids":{"type":"array","description":"Requested IDs skipped because available credits limited processing. Retry these IDs after adding credits.","items":{"type":"string","pattern":"^\\d+$"}}}},"GuestWalletAmount":{"description":"Confirmed USD amount for a guest wallet purchase.","type":"object","additionalProperties":false,"required":["amount_minor","currency"],"properties":{"amount_minor":{"type":"integer","minimum":1000,"maximum":25000,"description":"USD amount in cents. Accepted range is $10-$250.","example":1000},"currency":{"type":"string","const":"usd"}}},"GuestWalletAmountBounds":{"description":"Accepted guest wallet purchase range in USD cents.","type":"object","additionalProperties":false,"required":["currency","maximum_minor","minimum_minor"],"properties":{"currency":{"type":"string","const":"usd"},"maximum_minor":{"type":"integer","const":25000},"minimum_minor":{"type":"integer","const":1000}}},"GuestWalletPurchaseRequest":{"description":"User-confirmed guest wallet checkout request.","type":"object","additionalProperties":false,"required":["amount_minor","currency"],"properties":{"amount_minor":{"type":"integer","minimum":1000,"maximum":25000,"description":"Confirmed USD amount in cents.","example":1000},"currency":{"type":"string","const":"usd"}}},"GuestWalletCheckoutResponse":{"description":"Pending Stripe checkout and guest wallet purchase details.","type":"object","additionalProperties":false,"required":["account_required","amount","checkout_url","credits","expires_at","instructions","poll_after_seconds","purchase_id","requires_user_interaction","status","status_url","wallet_id"],"properties":{"account_required":{"type":"boolean","const":false},"amount":{"$ref":"#/components/schemas/GuestWalletAmount"},"api_key":{"type":"string","format":"password","description":"Paid-read bearer credential returned only by initial creation. Store it as a secret. Never place it in a URL or log.\n","example":"xq_example_returned_once"},"authorization":{"type":"object","additionalProperties":false,"required":["header","scheme"],"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"},"scheme":{"type":"string","enum":["Bearer"],"example":"Bearer"}}},"checkout_url":{"type":"string","format":"uri","pattern":"^https://buy\\.stripe\\.com/","description":"Raw Stripe-hosted checkout URL for user interaction.","example":"https://buy.stripe.com/example"},"credits":{"type":"string","pattern":"^\\d+$","description":"Credits granted after verified payment.","example":"66666"},"credential_notice":{"type":"string","const":"Store api_key and the Idempotency-Key securely before sharing checkout_url. No email recovery is available."},"expires_at":{"type":"string","format":"date-time","description":"Time when the pending checkout expires.","example":"2026-07-13T13:00:00.000Z"},"instructions":{"type":"string","const":"Give checkout_url to the user. They must complete payment on Stripe. Never submit payment for them. After payment, poll status_url every poll_after_seconds until latest_purchase.status is no longer pending."},"poll_after_seconds":{"type":"integer","const":2,"description":"Wait at least this long before polling status_url."},"purchase_id":{"type":"string","pattern":"^gp_[A-Za-z0-9_-]+$","example":"gp_example"},"requires_user_interaction":{"type":"boolean","const":true},"status":{"type":"string","enum":["creating","pending","paid","expired","failed","refunded","disputed"],"example":"pending"},"status_url":{"type":"string","format":"uri","const":"https://xquik.com/api/v1/guest-wallets/status"},"wallet_id":{"type":"string","pattern":"^gw_[A-Za-z0-9_-]+$","example":"gw_example"}}},"GuestWalletCreateResponse":{"description":"Initial guest wallet response containing the one-time key.","allOf":[{"$ref":"#/components/schemas/GuestWalletCheckoutResponse"},{"type":"object","required":["api_key","authorization","credential_notice"]}]},"GuestWalletTopupResponse":{"description":"Existing guest wallet top-up response without a new key.","allOf":[{"$ref":"#/components/schemas/GuestWalletCheckoutResponse"},{"not":{"anyOf":[{"type":"object","properties":{"api_key":{"type":"string"}},"required":["api_key"]},{"type":"object","properties":{"authorization":{"type":"object"}},"required":["authorization"]}]}}]},"GuestWalletPurchaseStatus":{"description":"Latest guest wallet purchase fulfillment state.","type":"object","additionalProperties":false,"required":["amount","checkout_url","credits","expires_at","purchase_id","status"],"properties":{"amount":{"$ref":"#/components/schemas/GuestWalletAmount"},"checkout_url":{"anyOf":[{"type":"string","format":"uri","pattern":"^https://buy\\.stripe\\.com/"},{"type":"null"}],"description":"Present only while the purchase is pending.","example":null},"credits":{"type":"string","pattern":"^\\d+$","example":"66666"},"expires_at":{"type":"string","format":"date-time","example":"2026-07-13T13:00:00.000Z"},"purchase_id":{"type":"string","pattern":"^gp_[A-Za-z0-9_-]+$","example":"gp_example"},"status":{"type":"string","enum":["creating","pending","paid","expired","failed","refunded","disputed"],"example":"paid"}}},"GuestWalletStatusResponse":{"description":"Current balance, usability, and latest guest purchase state.","type":"object","additionalProperties":false,"required":["balance","latest_purchase","poll_after_seconds","scope","status","top_up","usable","wallet_id"],"properties":{"balance":{"type":"string","pattern":"^\\d+$","example":"66666"},"latest_purchase":{"description":"Latest purchase state. This does not determine usability.","anyOf":[{"$ref":"#/components/schemas/GuestWalletPurchaseStatus"},{"type":"null"}],"example":{"amount":{"amount_minor":1000,"currency":"usd"},"checkout_url":null,"credits":"66666","expires_at":"2026-07-13T13:00:00.000Z","purchase_id":"gp_example","status":"paid"}},"poll_after_seconds":{"description":"Polling delay while payment is pending. Null means stop.","anyOf":[{"type":"integer","const":2},{"type":"null"}]},"scope":{"type":"string","const":"paid_reads"},"status":{"type":"string","description":"Combined wallet and pending-checkout state. A pending top-up can coexist with usable true. Terminal expired or failed states require a new guest wallet.\n","enum":["active","pending","expired","failed","frozen","closed"],"example":"active"},"top_up":{"description":"Top-up action when usable and no checkout is pending.","anyOf":[{"type":"object","additionalProperties":false,"required":["method","path"],"properties":{"method":{"type":"string","const":"POST"},"path":{"type":"string","const":"/api/v1/guest-wallets/topups"}}},{"type":"null"}]},"usable":{"type":"boolean","description":"Authoritative paid-read readiness. Use instead of status.","example":true},"wallet_id":{"type":"string","pattern":"^gw_[A-Za-z0-9_-]+$","example":"gw_example"}}},"GuestWalletCreateCheckoutAction":{"description":"Explicit direct REST action for a new guest wallet checkout.","type":"object","additionalProperties":false,"required":["account_required","amount_bounds","body","creates","method","path","provider","required_headers","requires_authentication","requires_user_confirmation","requires_user_interaction","response_fields","response_url_field"],"properties":{"account_required":{"type":"boolean","const":false},"amount_bounds":{"$ref":"#/components/schemas/GuestWalletAmountBounds"},"body":{"$ref":"#/components/schemas/GuestWalletPurchaseRequest"},"creates":{"type":"string","const":"checkout_url"},"method":{"type":"string","const":"POST"},"path":{"type":"string","const":"/api/v1/guest-wallets"},"provider":{"type":"string","const":"stripe"},"required_headers":{"type":"object","additionalProperties":false,"required":["Idempotency-Key"],"properties":{"Idempotency-Key":{"type":"string","const":"<cryptographically random UUID v4>"}}},"requires_authentication":{"type":"boolean","const":false},"requires_user_confirmation":{"type":"boolean","const":true},"requires_user_interaction":{"type":"boolean","const":true},"response_fields":{"type":"array","minItems":3,"maxItems":3,"prefixItems":[{"type":"string","const":"checkout_url"},{"type":"string","const":"api_key"},{"type":"string","const":"status_url"}],"items":{"type":"string","enum":["checkout_url","api_key","status_url"]}},"response_url_field":{"type":"string","const":"checkout_url"}}},"GuestWalletTopupCheckoutAction":{"description":"Explicit direct REST action for a guest wallet top-up.","type":"object","additionalProperties":false,"required":["account_required","amount_bounds","body","creates","method","path","provider","required_headers","requires_authentication","requires_user_confirmation","requires_user_interaction","response_fields","response_url_field"],"properties":{"account_required":{"type":"boolean","const":false},"amount_bounds":{"$ref":"#/components/schemas/GuestWalletAmountBounds"},"body":{"$ref":"#/components/schemas/GuestWalletPurchaseRequest"},"creates":{"type":"string","const":"checkout_url"},"method":{"type":"string","const":"POST"},"path":{"type":"string","const":"/api/v1/guest-wallets/topups"},"provider":{"type":"string","const":"stripe"},"required_headers":{"type":"object","additionalProperties":false,"required":["Idempotency-Key"],"properties":{"Idempotency-Key":{"type":"string","const":"<cryptographically random UUID v4>"}}},"requires_authentication":{"type":"boolean","const":true},"requires_user_confirmation":{"type":"boolean","const":true},"requires_user_interaction":{"type":"boolean","const":true},"response_fields":{"type":"array","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"checkout_url"},{"type":"string","const":"status_url"}],"items":{"type":"string","enum":["checkout_url","status_url"]}},"response_url_field":{"type":"string","const":"checkout_url"}}},"AnonymousGuestAuthenticationRequired":{"description":"Authentication error for a non-MPP anonymous paid read. The response also advertises optional accountless Stripe checkout after confirmation.\n","type":"object","additionalProperties":false,"required":["account_required","error","message","next_step","payment_options"],"properties":{"account_required":{"type":"boolean","const":false},"error":{"type":"string","const":"unauthenticated"},"message":{"type":"string","example":"Authentication required."},"next_step":{"type":"string","const":"Ask the user to confirm a USD amount before creating checkout."},"payment_options":{"type":"object","additionalProperties":false,"required":["guest_wallet"],"properties":{"guest_wallet":{"type":"object","additionalProperties":false,"required":["create_checkout"],"properties":{"create_checkout":{"$ref":"#/components/schemas/GuestWalletCreateCheckoutAction"}}}}}}},"GuestPaymentRequired":{"description":"Credit error for a paid-read guest key with only its accountless guest top-up action.\n","type":"object","additionalProperties":false,"required":["balance","error","message","next_step","payment_options","required","top_up_endpoint","top_up_url"],"properties":{"balance":{"type":"string","pattern":"^\\d+$","example":"0"},"error":{"type":"string","enum":["insufficient_credits","no_credits","no_subscription","subscription_inactive"],"example":"insufficient_credits"},"message":{"type":"string","example":"Insufficient credits. Top up or subscribe to continue."},"next_step":{"type":"string","const":"Ask the user to confirm a USD amount before creating checkout."},"payment_options":{"type":"object","additionalProperties":false,"required":["credits"],"properties":{"credits":{"type":"object","additionalProperties":false,"required":["create_checkout"],"properties":{"create_checkout":{"$ref":"#/components/schemas/GuestWalletTopupCheckoutAction"}}}}},"required":{"type":"string","pattern":"^\\d+$","example":"1"},"top_up_endpoint":{"type":"string","const":"/api/v1/guest-wallets/topups"},"top_up_url":{"type":"string","const":"POST /api/v1/guest-wallets/topups"}}},"AuthenticatedPaymentRequired":{"description":"Authenticated credit or subscription error with confirmation-gated Stripe checkout actions.","type":"object","additionalProperties":false,"required":["balance","dashboard","error","message","next_step","payment_options","required","top_up_endpoint","top_up_url"],"properties":{"balance":{"type":"string","pattern":"^\\d+$","description":"Available credits as a decimal string.","example":"0"},"dashboard":{"type":"string","const":"/dashboard/account","description":"Account page for manual billing management."},"error":{"type":"string","enum":["insufficient_credits","no_credits","no_subscription","subscription_inactive"],"example":"insufficient_credits"},"message":{"type":"string","example":"Insufficient credits. Top up or subscribe to continue."},"next_step":{"type":"string","const":"Ask the user to confirm a payment option before creating checkout."},"payment_options":{"type":"object","additionalProperties":false,"required":["credits","subscription"],"properties":{"credits":{"type":"object","additionalProperties":false,"required":["create_checkout"],"properties":{"create_checkout":{"type":"object","additionalProperties":false,"required":["body","creates","method","path","provider","requires_authentication","requires_user_confirmation","response_url_field"],"properties":{"body":{"type":"object","additionalProperties":false,"required":["dollars","locale"],"properties":{"dollars":{"type":"integer","const":10},"locale":{"type":"string","const":"en"}}},"creates":{"type":"string","const":"checkout_url"},"method":{"type":"string","const":"POST"},"path":{"type":"string","const":"/api/v1/credits/topup"},"provider":{"type":"string","const":"stripe"},"requires_authentication":{"type":"boolean","const":true},"requires_user_confirmation":{"type":"boolean","const":true},"response_url_field":{"type":"string","const":"url"}}}}},"subscription":{"type":"object","additionalProperties":false,"required":["create_checkout"],"properties":{"create_checkout":{"type":"object","additionalProperties":false,"required":["body","creates","method","path","provider","requires_authentication","requires_user_confirmation","response_url_field"],"properties":{"body":{"type":"object","additionalProperties":false,"required":["tier"],"properties":{"tier":{"type":"string","const":"starter"}}},"creates":{"type":"string","const":"checkout_url"},"method":{"type":"string","const":"POST"},"path":{"type":"string","const":"/api/v1/subscribe"},"provider":{"type":"string","const":"stripe"},"requires_authentication":{"type":"boolean","const":true},"requires_user_confirmation":{"type":"boolean","const":true},"response_url_field":{"type":"string","const":"url"}}}}}}},"required":{"type":"string","pattern":"^\\d+$","description":"Credits required for the blocked request.","example":"1"},"top_up_endpoint":{"type":"string","const":"/api/v1/credits/topup"},"top_up_url":{"type":"string","const":"POST /api/v1/credits/topup"}}},"MppPaymentRequired":{"description":"Anonymous payment requirement for a direct MPP operation. The response includes an MPP challenge and an accountless Stripe action.","type":"object","required":["account_required","detail","next_step","payment_options","status","title","type"],"properties":{"account_required":{"type":"boolean","const":false},"challengeId":{"type":"string","description":"Opaque identifier for the MPP payment challenge.","example":"mpp_challenge_example"},"detail":{"type":"string","example":"Payment is required."},"hint":{"type":"string","description":"Instructions for selecting and paying an MPP offer.","example":"Use a supported wallet with an offer from the WWW-Authenticate header."},"next_step":{"type":"string","const":"Ask the user to confirm a USD amount before creating checkout."},"payment_options":{"type":"object","additionalProperties":false,"required":["guest_wallet"],"properties":{"guest_wallet":{"type":"object","additionalProperties":false,"required":["create_checkout"],"properties":{"create_checkout":{"$ref":"#/components/schemas/GuestWalletCreateCheckoutAction"}}}}},"status":{"type":"integer","const":402},"title":{"type":"string","const":"Payment Required"},"type":{"type":"string","format":"uri","const":"https://paymentauth.org/problems/payment-required"}}},"Error":{"description":"Error response. Default v1 returns a legacy string error code. Send `xquik-api-contract: 2026-04-29` to receive the structured best-practice error object.\n","type":"object","required":["error"],"properties":{"error":{"x-stainless-naming":{"python":{"type_name":"ErrorValue"},"java":{"type_name":"ErrorValue"}},"example":"invalid_input","oneOf":[{"type":"string","title":"LegacyErrorCode","enum":["internal_error","account_already_connected","account_needs_reauth","account_not_found","account_required","account_restricted","api_key_limit_reached","article_not_found","dm_not_permitted","invalid_format","invalid_id","invalid_input","invalid_params","invalid_tool_type","invalid_tweet_id","invalid_tweet_url","invalid_user_id","invalid_user_ids","invalid_username","invalid_json","insufficient_credits","login_cooldown","login_failed","media_download_failed","missing_params","missing_query","monitor_already_exists","no_media","no_credits","no_subscription","not_found","payment_failed","rate_limit_exceeded","service_unavailable","style_not_found","subscription_inactive","tweet_not_found","unauthenticated","unsupported_field","user_not_found","x_account_feature_required","x_account_protected","x_account_suspended","x_api_rate_limited","x_api_unavailable","x_api_unauthorized","x_auth_failure","x_content_too_long","x_daily_limit","x_dm_not_allowed","x_duplicate_action","x_login_auth_failed","x_login_challenge","x_login_denied","x_login_failed","x_login_proxy_error","x_login_rate_limited","x_login_service_unavailable","x_login_suspended","x_rate_limited","x_rejected","x_target_not_found","x_transient_error","x_user_lookup_failed","x_write_ambiguous","x_write_failed"],"example":"invalid_input"},{"type":"object","title":"StructuredError","required":["message","type","code"],"properties":{"message":{"type":"string","example":"Invalid input. Check the request body."},"type":{"type":"string","enum":["api_error","authentication_error","billing_error","dependency_error","invalid_request_error","permission_error","rate_limit_error"],"example":"invalid_request_error"},"code":{"type":"string","title":"ErrorCode","enum":["internal_error","account_already_connected","account_needs_reauth","account_not_found","account_required","account_restricted","api_key_limit_reached","article_not_found","dm_not_permitted","invalid_format","invalid_id","invalid_input","invalid_params","invalid_tool_type","invalid_tweet_id","invalid_tweet_url","invalid_user_id","invalid_user_ids","invalid_username","invalid_json","insufficient_credits","login_cooldown","login_failed","media_download_failed","missing_params","missing_query","monitor_already_exists","no_media","no_credits","no_subscription","not_found","payment_failed","rate_limit_exceeded","service_unavailable","style_not_found","subscription_inactive","tweet_not_found","unauthenticated","unsupported_field","user_not_found","x_account_feature_required","x_account_protected","x_account_suspended","x_api_rate_limited","x_api_unavailable","x_api_unauthorized","x_auth_failure","x_content_too_long","x_daily_limit","x_dm_not_allowed","x_duplicate_action","x_login_auth_failed","x_login_challenge","x_login_denied","x_login_failed","x_login_proxy_error","x_login_rate_limited","x_login_service_unavailable","x_login_suspended","x_rate_limited","x_rejected","x_target_not_found","x_transient_error","x_user_lookup_failed","x_write_ambiguous","x_write_failed"],"example":"invalid_input"}}}]},"message":{"type":"string","description":"Human-readable error guidance."},"reason":{"type":"string","description":"Machine-readable reason for a login cooldown."},"retryAfter":{"type":"integer","minimum":1,"description":"Required wait in seconds."},"retryAfterMs":{"type":"integer","minimum":1,"description":"Required wait in milliseconds."}}},"EventType":{"description":"Type of monitor event fired when account activity occurs.","type":"string","enum":["tweet.new","tweet.reply","tweet.retweet","tweet.quote","tweet.media","tweet.link","tweet.poll","tweet.mention","tweet.hashtag","tweet.longform","profile.avatar.changed","profile.banner.changed","profile.name.changed","profile.username.changed","profile.bio.changed","profile.location.changed","profile.url.changed","profile.verified.changed","profile.protected.changed","profile.pinned_tweet.changed","profile.unavailable.changed"],"example":"tweet.new"},"EventTypeArray":{"description":"Array of event types to subscribe to.","type":"array","items":{"$ref":"#/components/schemas/EventType"},"minItems":1,"example":["tweet.new","tweet.reply"]},"ExtractionToolType":{"description":"Identifier for the extraction tool used to run a job.","type":"string","example":"follower_explorer","enum":["article_extractor","community_extractor","community_moderator_explorer","community_post_extractor","community_search","favoriters","follower_explorer","following_explorer","list_follower_explorer","list_member_extractor","list_post_extractor","mention_extractor","people_search","post_extractor","quote_extractor","reply_extractor","repost_extractor","space_explorer","thread_extractor","tweet_search_extractor","user_likes","user_media","verified_follower_explorer"]},"ApiKey":{"description":"API key metadata returned when listing keys.","type":"object","required":["id","name","prefix","isActive","createdAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":"string","format":"date-time"}}},"Monitor":{"description":"Account monitor that tracks activity for a given X user.","type":"object","required":["id","username","xUserId","eventTypes","isActive","createdAt","nextBillingAt"],"properties":{"id":{"type":"string","example":"42"},"username":{"type":"string","example":"elonmusk"},"xUserId":{"type":"string","example":"9876543210"},"eventTypes":{"$ref":"#/components/schemas/EventTypeArray","example":["tweet.new","tweet.reply"]},"isActive":{"type":"boolean","example":true},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"},"nextBillingAt":{"type":"string","format":"date-time","description":"Next hourly credit charge time for this account monitor.","example":"2025-01-15T12:00:00Z"}}},"KeywordMonitor":{"description":"Keyword monitor that tracks matching public X activity.","type":"object","required":["id","query","eventTypes","isActive","createdAt","nextBillingAt"],"properties":{"id":{"type":"string","example":"21"},"query":{"type":"string","example":"xquik OR \"x api\""},"eventTypes":{"$ref":"#/components/schemas/EventTypeArray","example":["tweet.new"]},"isActive":{"type":"boolean","example":true},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"},"nextBillingAt":{"type":"string","format":"date-time","description":"Next hourly credit charge time for this keyword query monitor.","example":"2025-01-15T12:00:00Z"}}},"Event":{"description":"Monitor event summary with source metadata and occurrence time.","type":"object","required":["id","type","monitorId","monitorType","occurredAt","data"],"properties":{"id":{"type":"string"},"type":{"$ref":"#/components/schemas/EventType"},"username":{"type":"string","description":"Account username, present for account monitor events."},"query":{"type":"string","description":"Keyword query, present for keyword monitor events."},"monitorId":{"type":"string","description":"Account monitor ID for account events, or keyword monitor ID for keyword events."},"monitorType":{"type":"string","enum":["account","keyword"],"description":"Source monitor type."},"keywordMonitorId":{"type":"string","description":"Keyword monitor ID, present for keyword monitor events."},"occurredAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true}}},"EventDetail":{"description":"Full monitor event including payload data and optional X event ID.","type":"object","required":["id","type","monitorId","monitorType","occurredAt","data"],"properties":{"id":{"type":"string","example":"42"},"type":{"$ref":"#/components/schemas/EventType","example":"tweet.new"},"username":{"type":"string","description":"Account username for this detailed monitor event.","example":"elonmusk"},"query":{"type":"string","description":"Keyword query for this detailed monitor event.","example":"xquik OR \"x api\""},"monitorId":{"type":"string","description":"Monitor ID associated with this detailed event payload.","example":"10"},"monitorType":{"type":"string","enum":["account","keyword"],"description":"Source monitor type for this detailed event.","example":"account"},"keywordMonitorId":{"type":"string","description":"Keyword monitor ID included on detailed keyword events.","example":"21"},"occurredAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"},"data":{"type":"object","additionalProperties":true,"x-stainless-any":true,"description":"Event payload - shape varies by event type (JSON)","x-stainless-terraform-type":"string","example":{"tweetId":"1234567890"}},"xEventId":{"type":"string","example":"1234567890"}}},"ExtractionJob":{"description":"Extraction job tracking status, tool type, and result count.","type":"object","required":["id","toolType","status","totalResults","createdAt"],"properties":{"id":{"type":"string"},"toolType":{"$ref":"#/components/schemas/ExtractionToolType"},"status":{"type":"string","enum":["running","completed","failed"]},"totalResults":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}},"DrawListItem":{"description":"Giveaway draw summary with entry counts and status.","type":"object","required":["id","tweetUrl","status","totalEntries","validEntries","createdAt"],"properties":{"id":{"type":"string","description":"Draw public ID for detail responses.","example":"f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345"},"tweetUrl":{"type":"string","format":"uri"},"status":{"type":"string"},"totalEntries":{"type":"integer"},"validEntries":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"drawnAt":{"type":"string","format":"date-time"}}},"DrawDetail":{"description":"Full giveaway draw with tweet metrics, entries, and timing.","type":"object","required":["id","tweetUrl","tweetId","tweetText","tweetAuthorUsername","status","totalEntries","validEntries","tweetLikeCount","tweetRetweetCount","tweetReplyCount","tweetQuoteCount","createdAt"],"properties":{"id":{"type":"string","description":"Draw public ID.","example":"f4bd00a2-7b4e-4e59-8e1b-72e2c9f12345"},"tweetUrl":{"type":"string","format":"uri"},"tweetId":{"type":"string"},"tweetText":{"type":"string"},"tweetAuthorUsername":{"type":"string"},"status":{"type":"string"},"totalEntries":{"type":"integer"},"validEntries":{"type":"integer"},"tweetLikeCount":{"type":"integer"},"tweetRetweetCount":{"type":"integer"},"tweetReplyCount":{"type":"integer"},"tweetQuoteCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"drawnAt":{"type":"string","format":"date-time"}}},"Winner":{"description":"Giveaway draw winner with position and backup flag.","type":"object","required":["authorUsername","tweetId","position","isBackup"],"properties":{"authorUsername":{"type":"string"},"tweetId":{"type":"string"},"position":{"type":"integer"},"isBackup":{"type":"boolean"}}},"Webhook":{"description":"Webhook endpoint registered to receive event deliveries.","type":"object","required":["id","url","eventTypes","isActive","consecutiveFailures","deliveryStatus","failureHardCap","createdAt"],"properties":{"id":{"type":"string","example":"42"},"url":{"type":"string","format":"uri","example":"https://example.com/webhooks/xquik"},"eventTypes":{"$ref":"#/components/schemas/EventTypeArray","example":["tweet.new","tweet.reply"]},"isActive":{"type":"boolean","example":true},"consecutiveFailures":{"type":"integer","description":"Consecutive failed delivery attempts since the last success.","example":0},"deliveryStatus":{"type":"string","enum":["active","paused","needs_attention"],"description":"Endpoint delivery state. needs_attention means delivery stopped after repeated failures.","example":"active"},"failureHardCap":{"type":"integer","description":"Consecutive delivery failures that pause the endpoint.","example":200},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"}}},"Delivery":{"description":"Webhook delivery attempt record with status and retry count.","type":"object","required":["id","streamEventId","status","attempts","createdAt"],"properties":{"id":{"type":"string"},"streamEventId":{"type":"string"},"status":{"type":"string"},"attempts":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"lastStatusCode":{"type":"integer"},"lastError":{"type":"string"}}},"ArticleAuthor":{"description":"X Article author profile fields returned when available.","type":"object","required":["id","name","username"],"properties":{"id":{"type":"string","example":"9876543210"},"name":{"type":"string","example":"Elon Musk"},"username":{"type":"string","example":"elonmusk"},"description":{"type":"string"},"location":{"type":"string"},"url":{"type":"string"},"createdAt":{"type":"string"},"followersCount":{"type":"integer"},"followingCount":{"type":"integer"},"statusesCount":{"type":"integer"},"mediaCount":{"type":"integer"},"favouritesCount":{"type":"integer"},"profilePicture":{"type":"string"},"profileBannerUrl":{"type":"string"},"isBlueVerified":{"type":"boolean"},"isVerified":{"type":"boolean"},"isTranslator":{"type":"boolean"},"protected":{"type":"boolean"},"canDm":{"type":"boolean"}}},"TweetMedia":{"description":"Normalized media attached to a tweet.","type":"object","required":["mediaUrl","type","url"],"properties":{"mediaUrl":{"type":"string","description":"Media preview URL"},"type":{"type":"string","enum":["photo","video","animated_gif"]},"url":{"type":"string","description":"X media link from the tweet"},"videoVariants":{"type":"array","description":"Available video encodings, ordered as returned","items":{"type":"object","required":["contentType","url"],"properties":{"bitrate":{"type":"integer"},"contentType":{"type":"string"},"url":{"type":"string"}}}}}},"EmbeddedTweet":{"description":"Quoted or retweeted tweet context. Every object includes id, text, and engagement metrics. A zero metric can mean X did not report the count. Author, media, and conversation fields appear when available.\n","type":"object","required":["id","text","retweetCount","replyCount","likeCount","quoteCount","viewCount","bookmarkCount"],"properties":{"id":{"type":"string"},"text":{"type":"string"},"type":{"type":"string"},"createdAt":{"type":"string"},"url":{"type":"string"},"lang":{"type":"string"},"retweetCount":{"type":"integer"},"replyCount":{"type":"integer"},"likeCount":{"type":"integer"},"quoteCount":{"type":"integer"},"viewCount":{"type":"integer"},"bookmarkCount":{"type":"integer"},"isReply":{"type":"boolean"},"isLimitedReply":{"type":"boolean"},"isNoteTweet":{"type":"boolean"},"isQuoteStatus":{"type":"boolean"},"inReplyToId":{"type":"string"},"inReplyToUserId":{"type":"string"},"inReplyToUsername":{"type":"string"},"conversationId":{"type":"string"},"source":{"type":"string"},"displayTextRange":{"type":"array","items":{"type":"integer"}},"contentDisclosure":{"$ref":"#/components/schemas/ContentDisclosure"},"entities":{"type":"object","additionalProperties":true,"x-stainless-any":true,"x-stainless-terraform-type":"string"},"media":{"type":"array","items":{"$ref":"#/components/schemas/TweetMedia"}},"author":{"$ref":"#/components/schemas/UserProfile"}}},"ContentDisclosure":{"description":"Content disclosure metadata shown by X when a tweet is labeled as paid partnership content or AI-generated media.","type":"object","properties":{"advertising":{"type":"object","properties":{"isPaidPromotion":{"type":"boolean","description":"True when X labels the tweet as paid promotion content.","example":true}}},"aiGenerated":{"type":"object","properties":{"detectionSource":{"type":"string","description":"Source of the AI-generated media disclosure.","example":"UserDeclared"},"canEdit":{"type":"boolean","description":"Whether the disclosure can be edited on X.","example":true},"hasAiGeneratedMedia":{"type":"boolean","description":"True when X labels the tweet as containing AI-generated media.","example":true}}}}},"TweetDetail":{"description":"Full tweet with text, engagement metrics, media, and metadata. A zero metric can mean X did not report the count.","type":"object","required":["id","text","retweetCount","replyCount","likeCount","quoteCount","viewCount","bookmarkCount"],"properties":{"id":{"type":"string","example":"1234567890"},"text":{"type":"string","example":"Just launched our new feature!"},"createdAt":{"type":"string","example":"2025-01-15T12:00:00Z"},"isNoteTweet":{"type":"boolean","description":"Whether this is a Note Tweet (long-form post, up to 25,000 characters)","example":false},"isReply":{"type":"boolean","description":"Whether this tweet is a reply to another tweet","example":false},"isLimitedReply":{"type":"boolean","description":"Whether replies are limited for this tweet","example":false},"isQuoteStatus":{"type":"boolean","description":"Whether this tweet quotes another tweet","example":false},"conversationId":{"type":"string","description":"ID of the root tweet in the conversation thread","example":"1234567890"},"source":{"type":"string","description":"Client application used to post this tweet","example":"Twitter Web App"},"type":{"type":"string","description":"Tweet result type","example":"tweet"},"url":{"type":"string","description":"Tweet permalink URL","example":"https://x.com/example_user/status/1234567890"},"lang":{"type":"string","description":"Tweet language code","example":"en"},"inReplyToId":{"type":"string","description":"Tweet ID being replied to","example":"1234567890"},"inReplyToUserId":{"type":"string","description":"User ID being replied to","example":"9876543210"},"inReplyToUsername":{"type":"string","description":"Username being replied to","example":"example_user"},"displayTextRange":{"type":"array","items":{"type":"integer"},"description":"Start and end offsets for rendered tweet text","example":[0,31]},"contentDisclosure":{"$ref":"#/components/schemas/ContentDisclosure"},"entities":{"type":"object","additionalProperties":true,"x-stainless-any":true,"x-stainless-terraform-type":"string","description":"Parsed entities from the tweet text (URLs, mentions, hashtags, media)"},"quoted_tweet":{"$ref":"#/components/schemas/EmbeddedTweet"},"retweeted_tweet":{"$ref":"#/components/schemas/EmbeddedTweet"},"author":{"$ref":"#/components/schemas/TweetAuthor"},"media":{"type":"array","items":{"$ref":"#/components/schemas/TweetMedia"},"description":"Attached media items, omitted when the tweet has no media"},"retweetCount":{"type":"integer","example":5},"replyCount":{"type":"integer","example":3},"likeCount":{"type":"integer","example":42},"quoteCount":{"type":"integer","example":1},"viewCount":{"type":"integer","example":1500},"bookmarkCount":{"type":"integer","example":2}}},"TweetAuthor":{"description":"Tweet author profile. The lookup route always includes follower count and verification state. Other profile fields appear when available.","allOf":[{"$ref":"#/components/schemas/UserProfile"},{"title":"TweetAuthorRequirements","type":"object","required":["followers","verified"]}]},"SearchTweet":{"description":"Tweet returned from search results with inline author info. A zero metric can mean X did not report the count.","type":"object","required":["id","text","retweetCount","replyCount","likeCount","quoteCount","viewCount","bookmarkCount"],"properties":{"id":{"type":"string","example":"1234567890"},"text":{"type":"string","example":"Just launched our new feature!"},"type":{"type":"string","example":"tweet"},"createdAt":{"type":"string","example":"2025-01-15T12:00:00Z"},"isNoteTweet":{"type":"boolean","description":"True for Note Tweets (long-form content, up to 25,000 characters)","example":false},"isReply":{"type":"boolean","description":"True when this search result is a reply","example":false},"isQuoteStatus":{"type":"boolean","description":"True when this search result quotes another tweet","example":false},"isLimitedReply":{"type":"boolean","description":"Whether the tweet has limited reply permissions","example":false},"inReplyToId":{"type":"string","description":"Tweet ID being replied to","example":"1234567890"},"inReplyToUserId":{"type":"string","description":"User ID being replied to","example":"9876543210"},"inReplyToUsername":{"type":"string","description":"Username being replied to","example":"example_user"},"conversationId":{"type":"string","description":"Root tweet ID for the search result conversation","example":"1234567890"},"source":{"type":"string","description":"Client application used to post the tweet","example":"Twitter Web App"},"displayTextRange":{"type":"array","items":{"type":"integer"},"description":"Start and end offsets for rendered tweet text","example":[0,31]},"contentDisclosure":{"$ref":"#/components/schemas/ContentDisclosure"},"entities":{"type":"object","additionalProperties":true,"description":"Parsed search-result entities including URLs, mentions, hashtags, and media markers"},"quoted_tweet":{"$ref":"#/components/schemas/EmbeddedTweet"},"retweeted_tweet":{"$ref":"#/components/schemas/EmbeddedTweet"},"media":{"type":"array","items":{"$ref":"#/components/schemas/TweetMedia"},"description":"Search-result media attachments, omitted when no media is present"},"url":{"type":"string","description":"Tweet permalink URL","example":"https://x.com/example_user/status/1234567890"},"lang":{"type":"string","description":"Tweet language code","example":"en"},"likeCount":{"type":"integer","example":42},"retweetCount":{"type":"integer","example":5},"replyCount":{"type":"integer","example":3},"quoteCount":{"type":"integer","example":1},"viewCount":{"type":"integer","example":1500},"bookmarkCount":{"type":"integer","example":2},"author":{"$ref":"#/components/schemas/UserProfile"}}},"UserProfile":{"description":"X user profile with bio, follower counts, and verification status.","type":"object","required":["id","username","name"],"properties":{"id":{"type":"string","example":"9876543210"},"username":{"type":"string","example":"elonmusk"},"name":{"type":"string","example":"Elon Musk"},"description":{"type":"string","example":"CEO of Tesla, SpaceX, and X"},"followers":{"type":"integer","example":150000000},"following":{"type":"integer","example":500},"verified":{"type":"boolean","example":true},"isBlueVerified":{"type":"boolean","description":"Whether X shows a blue verification badge","example":true},"isVerified":{"type":"boolean","description":"Whether X marks the profile as verified","example":true},"profilePicture":{"type":"string","example":"https://pbs.twimg.com/profile_images/example.jpg"},"coverPicture":{"type":"string","example":"https://pbs.twimg.com/profile_banners/example.jpg"},"profileBannerUrl":{"type":"string","description":"Original X profile banner field when available","example":"https://pbs.twimg.com/profile_banners/example.jpg"},"location":{"type":"string","example":"Austin, TX"},"createdAt":{"type":"string","example":"2009-06-02T20:12:29Z"},"statusesCount":{"type":"integer","example":35000},"mediaCount":{"type":"integer","example":1200},"canDm":{"type":"boolean","example":false},"protected":{"type":"boolean","description":"Whether the profile protects its posts","example":false},"url":{"type":"string","example":"https://xquik.com"},"favouritesCount":{"type":"integer","example":18000},"hasCustomTimelines":{"type":"boolean","example":true},"isTranslator":{"type":"boolean","example":false},"withheldInCountries":{"type":"array","items":{"type":"string"},"example":["DE"]},"possiblySensitive":{"type":"boolean","example":false},"pinnedTweetIds":{"type":"array","items":{"type":"string"},"example":["1234567890"]},"isAutomated":{"type":"boolean","example":false},"automatedBy":{"type":"string","example":"example_user"},"unavailable":{"type":"boolean","example":false},"unavailableReason":{"type":"string","example":"suspended"},"verifiedType":{"type":"string","example":"Business"},"communityRole":{"type":"string","description":"Community role when returned by community member reads","example":"Member"},"viewerFollowedBy":{"type":"boolean","description":"Whether this profile follows the authenticated viewer","example":false},"viewerFollowing":{"type":"boolean","description":"Whether the authenticated viewer follows this profile","example":true},"profile_bio":{"type":"object","additionalProperties":true,"x-stainless-any":true,"x-stainless-terraform-type":"string","description":"Structured profile bio with entity annotations","example":{"description":"CEO of Tesla, SpaceX, and X","entities":{"urls":[]}}}}},"Draft":{"description":"Saved tweet draft with optional topic and goal.","type":"object","required":["id","text","createdAt"],"properties":{"id":{"type":"string","example":"42"},"text":{"type":"string","example":"Draft tweet about AI trends"},"topic":{"type":"string","example":"Technology"},"goal":{"type":"string","example":"Engagement"},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"}}},"DraftDetail":{"description":"Full tweet draft including update timestamp.","type":"object","required":["id","text","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"42"},"text":{"type":"string","example":"Draft tweet about AI trends"},"topic":{"type":"string","example":"Technology"},"goal":{"type":"string","example":"Engagement"},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"},"updatedAt":{"type":"string","format":"date-time","example":"2025-01-16T09:30:00Z"}}},"StyleProfileSummary":{"description":"Style profile summary with tweet count and ownership flag.","type":"object","required":["xUsername","tweetCount","isOwnAccount","fetchedAt"],"properties":{"xUsername":{"type":"string","example":"elonmusk"},"tweetCount":{"type":"integer","example":50},"isOwnAccount":{"type":"boolean","example":true},"fetchedAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"}}},"StyleProfile":{"description":"Full style profile with sampled tweets used for tone analysis.","type":"object","required":["xUsername","tweetCount","isOwnAccount","fetchedAt","tweets"],"properties":{"xUsername":{"type":"string","example":"elonmusk"},"tweetCount":{"type":"integer","example":50},"isOwnAccount":{"type":"boolean","example":true},"fetchedAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"},"tweets":{"type":"array","items":{"type":"object","required":["id","text"],"properties":{"id":{"type":"string","example":"1234567890"},"text":{"type":"string","example":"Just launched our new feature!"},"createdAt":{"type":"string","example":"2025-01-15T12:00:00Z"},"authorUsername":{"type":"string","example":"elonmusk"}}},"example":[{"id":"1234567890","text":"Just launched our new feature!"}]}}},"RadarItem":{"description":"Trending topic with score, category, source, region, language, and source-specific metadata.","type":"object","required":["id","sourceId","title","score","category","source","region","language","metadata","publishedAt","createdAt"],"properties":{"id":{"type":"string","description":"Radar item identifier.","example":"4712"},"sourceId":{"type":"string","description":"Source-specific identifier used for deduplication.","example":"trustmrr_acme"},"title":{"type":"string","example":"AI Revolution in 2025"},"url":{"type":"string","example":"https://example.com/article/ai-revolution"},"score":{"type":"number","example":95.5},"category":{"type":"string","enum":["general","tech","dev","science","culture","politics","business","entertainment"],"example":"tech"},"source":{"type":"string","enum":["github","google_trends","hacker_news","polymarket","reddit","trustmrr","wikipedia"],"example":"trustmrr"},"region":{"type":"string","example":"global"},"language":{"type":"string","example":"en"},"metadata":{"type":"object","description":"Source-specific fields. Shape varies per source:\n- reddit: { subreddit: string, author: string }\n- github: { starsToday: number }\n- hacker_news: { points: number, numberComments: number }\n- google_trends: { approxTraffic: number }\n- polymarket: { volume24hr: number }\n- wikipedia: { views: number }\n- trustmrr: { mrr, growthPercent, last30Days, total, customers, activeSubscriptions, onSale, xHandle?, category?, askingPrice?, country?, growthMrrPercent?, multiple?, paymentProvider?, rank? }\n","additionalProperties":true},"publishedAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:01:00Z"},"description":{"type":"string","example":"AI is transforming every industry"},"imageUrl":{"type":"string","example":"https://example.com/images/ai.jpg"}}},"XAccount":{"description":"Linked X account summary with connection status, health, and timestamp metadata.","type":"object","required":["id","xUserId","xUsername","status","health","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"42"},"xUserId":{"type":"string","example":"9876543210"},"xUsername":{"type":"string","example":"elonmusk"},"status":{"type":"string","example":"active"},"health":{"type":"string","description":"Derived connection health. `healthy` = session active. `needsReauth` = user must submit fresh credentials. `locked` = X locked the account; unlock on x.com first. `suspended` = X banned the account. `recovering` = past cooldown, will auto-retry on next use. `temporaryIssue` = temporary connection problem; retry shortly.\n","enum":["healthy","locked","needsReauth","recovering","suspended","temporaryIssue"],"example":"healthy"},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"},"updatedAt":{"type":"string","format":"date-time","example":"2025-03-10T08:30:00Z"},"cookiesObtainedAt":{"type":"string","format":"date-time","example":"2025-03-10T08:30:00Z"}}},"XAccountConnectionChallenge":{"description":"Resumable account connection challenge. Submit the email code to finish the same connection attempt.","type":"object","required":["object","id","status","expiresAt","message","username"],"properties":{"object":{"type":"string","enum":["x_account_connection_challenge"],"example":"x_account_connection_challenge"},"id":{"type":"string","example":"xch_8vGd8Y9JvH6dV0xA"},"status":{"type":"string","enum":["requires_email_code"],"example":"requires_email_code"},"expiresAt":{"type":"string","format":"date-time","example":"2026-05-08T12:10:00Z"},"message":{"type":"string","example":"Enter the email verification code to continue."},"username":{"type":"string","example":"elonmusk"}}},"XAccountDetail":{"description":"Connected X account details with health and timestamp metadata.","type":"object","required":["id","xUserId","xUsername","status","health","createdAt"],"properties":{"id":{"type":"string","example":"42"},"xUserId":{"type":"string","example":"9876543210"},"xUsername":{"type":"string","example":"elonmusk"},"status":{"type":"string","example":"active"},"health":{"type":"string","enum":["healthy","locked","needsReauth","recovering","suspended","temporaryIssue"],"example":"healthy"},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"},"updatedAt":{"type":"string","format":"date-time","example":"2025-03-10T08:30:00Z"},"cookiesObtainedAt":{"type":"string","format":"date-time","example":"2025-03-10T08:30:00Z"}}},"SanitizedXAccount":{"description":"Sanitized X account summary returned by connect and reauth.","type":"object","required":["id","xUserId","xUsername","status","health","createdAt"],"properties":{"id":{"type":"string","example":"42"},"xUserId":{"type":"string","example":"9876543210"},"xUsername":{"type":"string","example":"elonmusk"},"status":{"type":"string","example":"active"},"health":{"type":"string","enum":["healthy","locked","needsReauth","recovering","suspended","temporaryIssue"],"example":"healthy"},"createdAt":{"type":"string","format":"date-time","example":"2025-01-15T12:00:00Z"}}},"XAccountBody":{"description":"Request body identifying an X account by username or ID.","type":"object","required":["account"],"properties":{"account":{"type":"string","description":"X account identifier (@username or account ID)","example":"@elonmusk"}}}}}}