{"openapi":"3.1.0","info":{"title":"Xquik API","version":"1.0","description":"Look up any tweet, user, or trend on X. Search tweets, check follower relationships, download media, and monitor accounts in real time. 31 pay-per-use read endpoints work without a subscription - just pay per call. 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## Official 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 user IDs or @usernames. Cost: $0.00105.\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.00105.\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 pay-per-use payments (no account needed). Media downloads, write endpoints, and automation features require an `x-api-key` header or OAuth 2.1 bearer token.\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":"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,"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":[{"apiKey":[]},{"oauthBearer":[]}],"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":[{"apiKey":[]},{"oauthBearer":[]}],"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":[{"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/subscribe":{"post":{"operationId":"subscribe","summary":"Get billing URL","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":160,"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","example":"1500000000000000000"},"targetListId":{"type":"string","example":"1234567890"},"targetSpaceId":{"type":"string","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","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":"xquikcom"},"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","example":"1500000000000000000"},"targetListId":{"type":"string","example":"1234567890"},"targetSpaceId":{"type":"string","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","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":"xquikcom"},"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":"No subscription, inactive subscription, no credits, or insufficient credits. Draws can fail before execution when the minimum draw cost is not affordable, or after execution when the 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,"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 inactive webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"webhook_inactive"}}}},"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/Unauthenticated"},"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":[]}],"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"},"attachment_url":{"type":"string","example":"https://x.com/elonmusk/status/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":{"description":"Tweet created","content":{"application/json":{"schema":{"type":"object","required":["tweetId","success","charged","chargedCredits"],"properties":{"tweetId":{"type":"string","example":"1234567890"},"success":{"type":"boolean","const":true,"example":true},"charged":{"type":"boolean","example":true},"chargedCredits":{"type":"string","description":"Credits charged for this tweet. Text-only tweets cost 10 credits; attached media adds 2 credits per started MB.","example":"12"},"writeActionId":{"type":"string","example":"42"}}},"example":{"tweetId":"1234567890","success":true,"charged":true,"chargedCredits":"12"}}}},"202":{"description":"Write was dispatched but final confirmation is still pending. Do not retry-send the same write. Poll the write action status instead.","content":{"application/json":{"schema":{"type":"object","required":["error","status","writeActionId","charged","chargedCredits","retryable"],"properties":{"error":{"type":"string","const":"x_write_unconfirmed"},"status":{"type":"string","const":"pending_confirmation"},"writeActionId":{"type":"string","example":"42"},"charged":{"type":"boolean","const":false},"chargedCredits":{"type":"string","example":"0"},"retryable":{"type":"boolean","const":false},"message":{"type":"string","example":"Action may have completed, but confirmation is still pending."}}},"example":{"error":"x_write_unconfirmed","status":"pending_confirmation","writeActionId":"42","charged":false,"chargedCredits":"0","retryable":false,"message":"Action may have completed, but confirmation is still pending."}}}},"400":{"description":"Invalid input or unsupported field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"InvalidInput":{"summary":"Invalid input","value":{"error":"invalid_input","message":"Either text or media is required"}},"UnsupportedField":{"summary":"Unsupported field on POST /x/tweets","value":{"error":"unsupported_field","message":"media_ids is not supported on POST /x/tweets. Pass media as an array of public image or MP4 video URLs.","retryable":false,"details":{"action":"create_tweet","suggestion":"Use the media field with public URLs instead of media_ids. Send up to 4 images or exactly 1 MP4 video."}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/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":{"description":"Write action status","content":{"application/json":{"schema":{"type":"object","required":["writeActionId","action","status","charged","chargedCredits","media","sendDispatched","retryable","createdAt"],"properties":{"writeActionId":{"type":"string","example":"42"},"action":{"type":"string","example":"create_tweet"},"status":{"type":"string","enum":["success","failed","pending_confirmation"],"example":"pending_confirmation"},"tweetId":{"type":"string","example":"1234567890"},"messageId":{"type":"string","example":"1234567890"},"targetId":{"type":["string","null"],"example":"1234567890"},"charged":{"type":"boolean","example":false},"chargedCredits":{"type":"string","example":"12"},"media":{"type":"object","required":["count","credits","kind","totalBytes"],"properties":{"count":{"type":"integer","example":1},"credits":{"type":"string","example":"2"},"kind":{"type":"string","enum":["none","image","video"],"example":"video"},"totalBytes":{"type":"string","example":"834921"}}},"sendDispatched":{"type":"boolean","example":true},"retryable":{"type":"boolean","const":false,"example":false},"confirmationAttempts":{"type":"integer","example":2},"confirmationSource":{"type":["string","null"],"example":"read_confirmation"},"createdAt":{"type":"string","format":"date-time","example":"2026-05-08T20:00:00.000Z"},"sendDispatchedAt":{"type":"string","format":"date-time","example":"2026-05-08T20:00:01.000Z"},"confirmationCheckedAt":{"type":"string","format":"date-time","example":"2026-05-08T20:00:05.000Z"},"confirmedAt":{"type":"string","format":"date-time","example":"2026-05-08T20:00:06.000Z"},"message":{"type":"string","example":"Confirmation is still pending."}}},"example":{"writeActionId":"42","action":"create_tweet","status":"pending_confirmation","charged":false,"chargedCredits":"0","media":{"count":0,"credits":"0","kind":"none","totalBytes":"0"},"sendDispatched":true,"retryable":false,"confirmationAttempts":2,"confirmationSource":null,"createdAt":"2026-05-08T20:00:00.000Z"}}}},"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":{"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":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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/Unauthenticated"},"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":{"amount":"1050","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"},"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":{"type":"object","required":["id","name","username"],"properties":{"id":{"type":"string","example":"9876543210"},"name":{"type":"string","example":"Elon Musk"},"username":{"type":"string","example":"elonmusk"},"profilePicture":{"type":"string","example":"https://pbs.twimg.com/profile_images/example.jpg"}}}}},"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":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"charge","method":"tempo"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Tweet ID"}],"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":[{"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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/RateLimitedByX"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/api/v1/x/tweets/{id}/like":{"post":{"operationId":"likeTweet","summary":"Like tweet","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/RateLimitedByX"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}},"delete":{"operationId":"unlikeTweet","summary":"Unlike tweet","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/RateLimitedByX"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/api/v1/x/tweets/{id}/retweet":{"post":{"operationId":"retweet","summary":"Retweet","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/RateLimitedByX"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}},"delete":{"operationId":"unretweet","summary":"Unretweet","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/RateLimitedByX"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/api/v1/x/users/batch":{"get":{"operationId":"getBatchUsers","summary":"Look up multiple users by IDs in one call","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated user IDs (max 100)"}],"responses":{"200":{"description":"List of users","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"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/x/users/search":{"get":{"operationId":"searchUsers","summary":"Search users by name or username","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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/Unauthenticated"},"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":{"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":[{"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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}},"delete":{"operationId":"unfollowUser","summary":"Unfollow user","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/api/v1/x/users/{id}/remove-follower":{"post":{"operationId":"removeFollower","summary":"Remove follower","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/api/v1/x/followers/check":{"get":{"operationId":"checkFollow","summary":"Check if one user follows another","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"1050","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"charge","method":"tempo"},"parameters":[{"name":"source","in":"query","required":true,"schema":{"type":"string"},"description":"Username to check (without @)"},{"name":"target","in":"query","required":true,"schema":{"type":"string"},"description":"Target username (without @)"}],"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 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":[{"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":{"description":"DM sent","content":{"application/json":{"schema":{"type":"object","required":["messageId","success"],"properties":{"messageId":{"type":"string","example":"1234567890123456789"},"success":{"type":"boolean","const":true}}}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/api/v1/x/media":{"post":{"operationId":"uploadMedia","summary":"Upload media","tags":["Media"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"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":{"description":"Media uploaded","content":{"application/json":{"schema":{"type":"object","required":["mediaId","mediaUrl","success"],"properties":{"mediaId":{"type":"string","example":"1234567890123456789"},"mediaUrl":{"type":"string","format":"uri","description":"Public media URL for tweet `media` arrays.","example":"https://media.xquik.com/uploads/1234567890123456789.png"},"success":{"type":"boolean","const":true}}}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/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":[]}],"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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/api/v1/x/profile/avatar":{"patch":{"operationId":"updateAvatar","summary":"Update profile avatar","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/api/v1/x/profile/banner":{"patch":{"operationId":"updateBanner","summary":"Update profile banner","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/api/v1/x/communities":{"post":{"operationId":"createCommunity","summary":"Create community","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"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":{"description":"Community created","content":{"application/json":{"schema":{"type":"object","required":["communityId","success"],"properties":{"communityId":{"type":"string","example":"1500000000000000000"},"communityName":{"type":"string","example":"Tesla Fans"},"success":{"type":"boolean","const":true,"example":true}}},"example":{"communityId":"1500000000000000000","communityName":"Tesla Fans","success":true}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/api/v1/x/communities/{id}":{"delete":{"operationId":"deleteCommunity","summary":"Delete community","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/api/v1/x/communities/{id}/join":{"post":{"operationId":"joinCommunity","summary":"Join community","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}},"delete":{"operationId":"leaveCommunity","summary":"Leave community","tags":["X Write"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"parameters":[{"$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/Success"},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountAuthError"},"404":{"$ref":"#/components/responses/XAccountNotFound"},"422":{"$ref":"#/components/responses/WriteRejected"},"429":{"$ref":"#/components/responses/WriteRateLimited"},"500":{"$ref":"#/components/responses/WriteError"},"503":{"$ref":"#/components/responses/TransientError"}}}},"/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":"elonmusk"},"email":{"type":"string","description":"Account email","example":"user@example.com"},"password":{"type":"string","description":"Account password","example":"s3cur3Pa$$w0rd"},"totp_secret":{"type":"string","description":"TOTP secret for 2FA","example":"JBSWY3DPEHPK3PXP"}}},"example":{"username":"elonmusk","email":"user@example.com","password":"s3cur3Pa$$w0rd"}}}},"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":"123456"}}},"example":{"email_code":"123456"}}}},"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":"s3cur3Pa$$w0rd"},"totp_secret":{"type":"string","description":"TOTP secret for 2FA re-authentication","example":"JBSWY3DPEHPK3PXP"},"email":{"type":"string","description":"Email for the X account (updates stored email)","example":"user@example.com"}}},"example":{"password":"password_value","totp_secret":"totp_secret_value"}}}},"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":{"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/tickets":{"post":{"operationId":"createTicket","summary":"Create a support ticket","tags":["Support"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"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."}}}},"responses":{"201":{"description":"Ticket created","content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string","example":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6"}}},"example":{"publicId":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"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"}}},"example":[{"body":"I am unable to connect my X account.","sender":"user","createdAt":"2025-01-15T12:00:00Z"}]}}},"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"}]}}}},"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"}],"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."}}}},"responses":{"201":{"description":"Message added","content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string","example":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6"}}},"example":{"publicId":"tkt_a1b2c3d4e5f6a1b2c3d4e5f6"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"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":"Top up credits balance","tags":["Subscribe"],"security":[{"apiKey":[]},{"oauthBearer":[]}],"requestBody":{"required":true,"description":"Dollar amount to add to the account balance.","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 checkout URL","content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Checkout URL where the user completes the top-up payment.","example":"https://xquik.com/billing/checkout/session"}}},"example":{"url":"https://xquik.com/billing/checkout/session"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/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":[{"apiKey":[]},{"oauthBearer":[]}],"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 users who liked a tweet","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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"}],"responses":{"200":{"description":"List of users who liked the tweet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"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/x/users/{id}/tweets":{"get":{"operationId":"getUserTweets","summary":"List recent tweets posted by a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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"},{"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/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/users/{id}/likes":{"get":{"operationId":"getUserLikes","summary":"List tweets liked by a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for liked tweets"},{"$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/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/users/{id}/media":{"get":{"operationId":"getUserMedia","summary":"List media tweets posted by a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID for media lookup"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for media tweets"},{"$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/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/users/{id}/followers-you-know":{"get":{"operationId":"getFollowersYouKnow","summary":"List mutual followers between you and a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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"}],"responses":{"200":{"description":"List of mutual followers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"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/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":{"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)"},"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":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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"},"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/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}/moderators":{"get":{"operationId":"getCommunityModerators","summary":"List moderators of a community","tags":["Communities"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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/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}/tweets":{"get":{"operationId":"getCommunityTweets","summary":"List tweets posted in a community","tags":["Communities"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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"}],"responses":{"200":{"description":"List of community tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"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/search":{"get":{"operationId":"searchCommunities","summary":"Search for communities by keyword","tags":["Communities"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query"},{"name":"queryType","in":"query","schema":{"type":"string"},"description":"Sort order (Latest or Top)"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for community search"}],"responses":{"200":{"description":"Community search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"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/x/communities/tweets":{"get":{"operationId":"getAllCommunityTweets","summary":"List tweets across all communities","tags":["Communities"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query for cross-community tweets"},{"name":"queryType","in":"query","schema":{"type":"string"},"description":"Sort order for cross-community results (Latest or Top)"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for cross-community results"}],"responses":{"200":{"description":"Paginated list of tweets from all communities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"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/x/lists/{id}/followers":{"get":{"operationId":"getListFollowers","summary":"List followers of an X List","tags":["Lists"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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"}],"responses":{"200":{"description":"List of followers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"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/lists/{id}/members":{"get":{"operationId":"getListMembers","summary":"List members of an X List","tags":["Lists"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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"},"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/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/lists/{id}/tweets":{"get":{"operationId":"getListTweets","summary":"List tweets from an X List","tags":["Lists"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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"},{"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/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/tweets/{id}/quotes":{"get":{"operationId":"getTweetQuotes","summary":"List quote tweets of a tweet","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Tweet ID to get quotes"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor for quote tweets"},{"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/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/{id}/replies":{"get":{"operationId":"getTweetReplies","summary":"List replies to a tweet","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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"},{"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/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/{id}/retweeters":{"get":{"operationId":"getTweetRetweeters","summary":"List users who retweeted a tweet","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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"}],"responses":{"200":{"description":"List of retweeters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"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/x/tweets/{id}/thread":{"get":{"operationId":"getTweetThread","summary":"Get full conversation thread for a tweet","tags":["Tweets"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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"}],"responses":{"200":{"description":"Thread tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTweets"}}}},"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/x/users/{id}/followers":{"get":{"operationId":"getUserFollowers","summary":"List followers of a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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 for following lists. Prefer cursor."},{"name":"pageSize","in":"query","schema":{"type":"integer"},"description":"Items per page (20-200, default 200). 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"},{"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/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/users/{id}/following":{"get":{"operationId":"getUserFollowing","summary":"List accounts a user follows","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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."},{"name":"pageSize","in":"query","schema":{"type":"integer"},"description":"Results per page (20-200, default 200). 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"},{"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/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/users/{id}/mentions":{"get":{"operationId":"getUserMentions","summary":"List tweets mentioning a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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"},{"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/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/users/{id}/verified-followers":{"get":{"operationId":"getUserVerifiedFollowers","summary":"List verified followers of a user","tags":["Users"],"security":[{"apiKey":[]},{"oauthBearer":[]},{}],"x-payment-info":{"amount":"150","currency":"0x20c000000000000000000000b9537d11c60e8b50","intent":"session","method":"tempo"},"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"}],"responses":{"200":{"description":"List of verified followers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedUsers"}}}},"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"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key passed via the x-api-key header. Xquik-Api-Key is accepted as a non-breaking vendor-prefixed alias."},"oauthBearer":{"type":"http","scheme":"bearer","description":"OAuth 2.1 access token"}},"parameters":{"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}},"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":{"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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthenticated","message":"Authentication required. Provide a valid API key or bearer token."}}}},"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. Returns a WWW-Authenticate header with an MPP challenge for pay-per-use endpoints, or indicates a subscription/credit issue for identity-authenticated endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"insufficient_credits","message":"Insufficient credits"}}}},"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, x_daily_limit (429 - account reached daily posting limit, wait 24 hours), and x_write_unconfirmed (202 - action may have completed but could not be confirmed, verify 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":{"$ref":"#/components/schemas/Error"},"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."}}}},"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":"Could not authenticate with X. The provided credentials (username, password, or TOTP secret) were rejected. Returns error code `login_failed`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"login_failed","message":"Login failed. Check credentials and try again."}}}},"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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"login_cooldown","message":"Login is temporarily paused"}}}},"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","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":{"PaginatedTweets":{"description":"Paginated list of tweets with cursor-based navigation. For paid authenticated calls, requested page size is an upper bound: remaining credits can reduce the returned item count, and 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!"}]},"has_next_page":{"type":"boolean","example":true},"next_cursor":{"type":"string","example":"DAACCgACGRElMJcAAA"}}},"PaginatedUsers":{"description":"Paginated list of user profiles with cursor-based navigation. For paid authenticated calls, requested page size is an upper bound: remaining credits can reduce the returned item count, and 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"}}},"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":{"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_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","webhook_inactive","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","x_write_unconfirmed"],"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_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","webhook_inactive","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","x_write_unconfirmed"],"example":"invalid_input"}}}]}}},"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","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},"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"}}},"TweetDetail":{"description":"Full tweet with text, engagement metrics, media, and metadata.","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},"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"},"entities":{"type":"object","additionalProperties":true,"description":"Parsed entities from the tweet text (URLs, mentions, hashtags, media)"},"quoted_tweet":{"type":"object","additionalProperties":true,"description":"The quoted tweet object, present when isQuoteStatus is true"},"media":{"type":"array","items":{"type":"object","properties":{"mediaUrl":{"type":"string","example":"https://pbs.twimg.com/media/example.jpg"},"type":{"type":"string","enum":["photo","video","animated_gif"],"example":"photo"},"url":{"type":"string","example":"https://t.co/abc123"}}},"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":"Author of a tweet with follower count and verification status.","type":"object","required":["id","username","followers","verified"],"properties":{"id":{"type":"string","example":"9876543210"},"username":{"type":"string","example":"elonmusk"},"followers":{"type":"integer","example":150000000},"verified":{"type":"boolean","example":true},"profilePicture":{"type":"string","example":"https://pbs.twimg.com/profile_images/example.jpg"}}},"SearchTweet":{"description":"Tweet returned from search results with inline author info.","type":"object","required":["id","text"],"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":"xquikcom"},"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]},"entities":{"type":"object","additionalProperties":true,"description":"Parsed search-result entities including URLs, mentions, hashtags, and media markers"},"quoted_tweet":{"type":"object","additionalProperties":true,"description":"Embedded quoted tweet, omitted when not a quote tweet"},"retweeted_tweet":{"type":"object","additionalProperties":true,"description":"Original retweeted tweet, omitted when not a retweet"},"media":{"type":"array","items":{"type":"object","properties":{"mediaUrl":{"type":"string","example":"https://pbs.twimg.com/media/example.jpg"},"type":{"type":"string","enum":["photo","video","animated_gif"],"example":"photo"},"url":{"type":"string","example":"https://t.co/abc123"}}},"description":"Search-result media attachments, omitted when no media is present"},"url":{"type":"string","description":"Tweet permalink URL","example":"https://x.com/xquikcom/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},"profilePicture":{"type":"string","example":"https://pbs.twimg.com/profile_images/example.jpg"},"coverPicture":{"type":"string","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},"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":"xquikcom"},"unavailable":{"type":"boolean","example":false},"unavailableReason":{"type":"string","example":"suspended"},"verifiedType":{"type":"string","example":"Business"},"profile_bio":{"type":"object","additionalProperties":true,"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 login/cookie health. `healthy` = cookies valid. `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` = transient backend 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":"Full X account details with status, cookies, and update timestamp.","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"}}}}}}