openapi: 3.2.0 info: title: Adanos Market Sentiment X/Twitter Stocks API description: Market sentiment and attention data for **stocks** across **Reddit**, **X/Twitter**, **financial news**, and **Polymarket**, plus a separate **Reddit crypto** API and direct finance-tuned **text sentiment analysis** (1,000+ term finance lexicon). termsOfService: https://adanos.org/terms contact: name: API Support url: https://api.adanos.org/ email: support@adanos.org license: name: MIT (OpenAPI document only) url: https://opensource.org/licenses/MIT version: 1.50.0 servers: - url: https://api.adanos.org description: Production tags: - name: X/Twitter Stocks description: Fast-moving stock attention from X/Twitter cashtags and tweet engagement, useful for momentum discovery and validation. paths: /x/stocks/v1/trending: get: tags: - X/Twitter Stocks summary: Trending stocks description: 'Returns the stocks with the strongest X/Twitter discussion activity in the selected period, ranked by `buzz_score`. **Includes:** - `buzz_score`: normalized 0-100 activity score used for ranking - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement or Grok rank movement. For `from`/`to`, anchors at `to` (or now when `to` is today) - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals - `mentions`, `unique_tweets`, `total_upvotes`: volume and engagement signals - `trend_history`: independent UTC-day buzz scores, oldest to newest; minimum 7 values; the live final value describes today so far and can differ from the selected-period `buzz_score`; missing days are `0.0`' operationId: getXTrendingStocks security: - ApiKeyAuth: [] parameters: - name: from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: Start date in YYYY-MM-DD. Inclusive UTC date. title: From description: Start date in YYYY-MM-DD. Inclusive UTC date. - name: to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. title: To description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. - name: days in: query required: false schema: type: integer maximum: 365 minimum: 1 description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. title: Days description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. deprecated: true x-adanos-hide-in-request-client: true - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum stocks to return examples: - 20 default: 20 title: Limit description: Maximum stocks to return - name: offset in: query required: false schema: type: integer minimum: 0 description: Number of items to skip for pagination examples: - 0 default: 0 title: Offset description: Number of items to skip for pagination - name: type in: query required: false schema: anyOf: - enum: - stock - etf - all type: string - type: 'null' description: Filter by asset type. Omit or use 'all' for all assets. examples: - stock title: Type description: Filter by asset type. Omit or use 'all' for all assets. responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/XTrendingStock' title: Response Getxtrendingstocks example: - ticker: TSLA company_name: Tesla, Inc. buzz_score: 72.5 trend: rising mentions: 156 sentiment_score: 0.35 bullish_pct: 45 bearish_pct: 12 total_upvotes: 2847 unique_tweets: 42 trend_history: - 45.2 - 48.1 - 52.3 - 55.0 - 58.2 - 61.5 - 64.8 headers: X-Request-ID: description: Request correlation identifier returned by the API and included in structured application logs. schema: type: string example: adnos.req-20260423.abc12345 Cache-Control: description: HTTP cache policy returned by the API. schema: type: string example: private, max-age=30 Vary: description: Headers that private client caches must include in their cache key. schema: type: string example: X-API-Key, Authorization, Accept-Encoding X-RateLimit-Limit-Monthly: description: Monthly request quota for the authenticated account. schema: type: string example: '250' X-RateLimit-Remaining-Monthly: description: Remaining monthly requests for the authenticated account. schema: type: string example: '247' X-RateLimit-Used-Monthly: description: Requests already consumed in the account's current monthly quota window. schema: type: string example: '3' X-RateLimit-Reset-Monthly: description: ISO 8601 timestamp when the current monthly quota window resets. schema: type: string format: date-time example: '2026-07-29T14:03:00Z' X-RateLimit-Limit-Burst: description: Per-minute burst request quota for the authenticated account. schema: type: string example: '100' X-RateLimit-Remaining-Burst: description: Remaining requests in the current per-minute burst window. schema: type: string example: '99' X-RateLimit-Reset-Burst: description: ISO 8601 timestamp when the current burst rate-limit window resets. schema: type: string format: date-time example: '2026-04-28T14:30:00Z' X-Account-Type: description: Account tier resolved from the API key. schema: type: string enum: - free - hobby - professional - premium example: free '401': description: Authentication failed content: application/json: examples: missing: summary: Missing API key value: detail: Missing API key. Include 'X-API-Key' header. invalid: summary: Invalid API key value: detail: Invalid API key. revoked: summary: Revoked API key value: detail: API key has been revoked. schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Historical data limit exceeded content: application/json: example: detail: error: Historical data limit exceeded message: 'Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing' requested_days: 60 enforced_quantity: lookback_days max_days: 30 account_type: free schema: $ref: '#/components/schemas/HistoricalLimitError' '429': description: Rate limit exceeded content: application/json: examples: burst: summary: Fleet burst limit exceeded value: detail: error: Burst rate limit exceeded message: Too many requests. Limit is 100 requests per minute. limit: 100 used: 100 account_type: free local: summary: Local backup limiter exceeded value: detail: error: Rate limit exceeded message: 'Rate limit exceeded: 100 per 1 minute' limit: 100 account_type: free schema: $ref: '#/components/schemas/RateLimitError' '422': description: Invalid period or query parameters content: application/json: examples: platform_availability: summary: Period starts before platform data availability value: detail: error: Invalid period message: Requested period starts before this platform's public data availability. period_from: '2025-03-17' available_since: '2026-03-07' platform: news validation: summary: Query parameter validation failed value: detail: - type: greater_than_equal loc: - query - days msg: Input should be greater than or equal to 1 input: '0' ctx: ge: 1 schema: anyOf: - $ref: '#/components/schemas/InvalidPeriodError' - $ref: '#/components/schemas/HTTPValidationError' title: Response 422 Getxtrendingstocks '503': description: Database temporarily unavailable content: application/json: example: detail: Database temporarily unavailable schema: $ref: '#/components/schemas/ErrorResponse' '504': description: Analytics request deadline exceeded content: application/json: example: detail: Request deadline exceeded schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: curl label: cURL source: "curl \"https://api.adanos.org/x/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\" \\\n -H \"X-API-Key: sk_live_your_key_here\"" - lang: javascript label: JavaScript source: "const response = await fetch(\"https://api.adanos.org/x/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\", {\n headers: {\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);" - lang: python label: Python source: "import requests\n\nresponse = requests.get(\n \"https://api.adanos.org/x/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\",\n headers={\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())" /x/stocks/v1/trending/sectors: get: tags: - X/Twitter Stocks summary: Trending sectors description: 'Returns the sectors with the strongest aggregated X/Twitter stock discussion in the selected period, ranked by `buzz_score`. **Includes:** - `buzz_score`: normalized 0-100 activity score used for ranking - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement or Grok rank movement. For `from`/`to`, anchors at `to` (or now when `to` is today) - `mentions`, `unique_tickers`, `total_upvotes`: volume and engagement signals - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals - `top_tickers`: up to 5 tickers driving the sector result - `trend_history`: independent daily sector buzz scores, oldest to newest; length is max(requested days, 7); the live final value describes today so far and can differ from period `buzz_score`' operationId: getXTrendingSectors security: - ApiKeyAuth: [] parameters: - name: from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: Start date in YYYY-MM-DD. Inclusive UTC date. title: From description: Start date in YYYY-MM-DD. Inclusive UTC date. - name: to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. title: To description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. - name: days in: query required: false schema: type: integer maximum: 365 minimum: 1 description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. title: Days description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. deprecated: true x-adanos-hide-in-request-client: true - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of results examples: - 10 default: 20 title: Limit description: Maximum number of results - name: offset in: query required: false schema: type: integer minimum: 0 description: Number of items to skip for pagination examples: - 0 default: 0 title: Offset description: Number of items to skip for pagination responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/XTrendingSector' title: Response Getxtrendingsectors example: - buzz_score: 78.4 trend: rising mentions: 4523 unique_tickers: 34 unique_authors: 156 sentiment_score: 0.28 bullish_pct: 54 bearish_pct: 22 total_upvotes: 128450 trend_history: - 45.2 - 48.1 - 52.3 - 55.0 - 58.2 - 61.5 - 78.4 top_tickers: - NVDA - AAPL - MSFT - AMD - GOOGL sector: Technology headers: X-Request-ID: description: Request correlation identifier returned by the API and included in structured application logs. schema: type: string example: adnos.req-20260423.abc12345 Cache-Control: description: HTTP cache policy returned by the API. schema: type: string example: private, max-age=300 Vary: description: Headers that private client caches must include in their cache key. schema: type: string example: X-API-Key, Authorization, Accept-Encoding X-RateLimit-Limit-Monthly: description: Monthly request quota for the authenticated account. schema: type: string example: '250' X-RateLimit-Remaining-Monthly: description: Remaining monthly requests for the authenticated account. schema: type: string example: '247' X-RateLimit-Used-Monthly: description: Requests already consumed in the account's current monthly quota window. schema: type: string example: '3' X-RateLimit-Reset-Monthly: description: ISO 8601 timestamp when the current monthly quota window resets. schema: type: string format: date-time example: '2026-07-29T14:03:00Z' X-RateLimit-Limit-Burst: description: Per-minute burst request quota for the authenticated account. schema: type: string example: '100' X-RateLimit-Remaining-Burst: description: Remaining requests in the current per-minute burst window. schema: type: string example: '99' X-RateLimit-Reset-Burst: description: ISO 8601 timestamp when the current burst rate-limit window resets. schema: type: string format: date-time example: '2026-04-28T14:30:00Z' X-Account-Type: description: Account tier resolved from the API key. schema: type: string enum: - free - hobby - professional - premium example: free '401': description: Authentication failed content: application/json: examples: missing: summary: Missing API key value: detail: Missing API key. Include 'X-API-Key' header. invalid: summary: Invalid API key value: detail: Invalid API key. revoked: summary: Revoked API key value: detail: API key has been revoked. schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Historical data limit exceeded content: application/json: example: detail: error: Historical data limit exceeded message: 'Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing' requested_days: 60 enforced_quantity: lookback_days max_days: 30 account_type: free schema: $ref: '#/components/schemas/HistoricalLimitError' '429': description: Rate limit exceeded content: application/json: examples: burst: summary: Fleet burst limit exceeded value: detail: error: Burst rate limit exceeded message: Too many requests. Limit is 100 requests per minute. limit: 100 used: 100 account_type: free local: summary: Local backup limiter exceeded value: detail: error: Rate limit exceeded message: 'Rate limit exceeded: 100 per 1 minute' limit: 100 account_type: free schema: $ref: '#/components/schemas/RateLimitError' '422': description: Invalid period or query parameters content: application/json: examples: platform_availability: summary: Period starts before platform data availability value: detail: error: Invalid period message: Requested period starts before this platform's public data availability. period_from: '2025-03-17' available_since: '2026-03-07' platform: news validation: summary: Query parameter validation failed value: detail: - type: greater_than_equal loc: - query - days msg: Input should be greater than or equal to 1 input: '0' ctx: ge: 1 schema: anyOf: - $ref: '#/components/schemas/InvalidPeriodError' - $ref: '#/components/schemas/HTTPValidationError' title: Response 422 Getxtrendingsectors '503': description: Database temporarily unavailable content: application/json: example: detail: Database temporarily unavailable schema: $ref: '#/components/schemas/ErrorResponse' '504': description: Analytics request deadline exceeded content: application/json: example: detail: Request deadline exceeded schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: curl label: cURL source: "curl \"https://api.adanos.org/x/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\" \\\n -H \"X-API-Key: sk_live_your_key_here\"" - lang: javascript label: JavaScript source: "const response = await fetch(\"https://api.adanos.org/x/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\", {\n headers: {\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);" - lang: python label: Python source: "import requests\n\nresponse = requests.get(\n \"https://api.adanos.org/x/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\",\n headers={\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())" /x/stocks/v1/trending/countries: get: tags: - X/Twitter Stocks summary: Trending countries description: 'Returns the countries with the strongest aggregated X/Twitter stock discussion in the selected period, ranked by `buzz_score`. **Includes:** - `buzz_score`: normalized 0-100 activity score used for ranking - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement or Grok rank movement. For `from`/`to`, anchors at `to` (or now when `to` is today) - `mentions`, `unique_tickers`, `total_upvotes`: volume and engagement signals - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals - `top_tickers`: up to 5 tickers driving the country result - `trend_history`: independent daily country buzz scores, oldest to newest; length is max(requested days, 7); the live final value describes today so far and can differ from period `buzz_score`' operationId: getXTrendingCountries security: - ApiKeyAuth: [] parameters: - name: from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: Start date in YYYY-MM-DD. Inclusive UTC date. title: From description: Start date in YYYY-MM-DD. Inclusive UTC date. - name: to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. title: To description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. - name: days in: query required: false schema: type: integer maximum: 365 minimum: 1 description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. title: Days description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. deprecated: true x-adanos-hide-in-request-client: true - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of results examples: - 10 default: 20 title: Limit description: Maximum number of results - name: offset in: query required: false schema: type: integer minimum: 0 description: Number of items to skip for pagination examples: - 0 default: 0 title: Offset description: Number of items to skip for pagination responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/XTrendingCountry' title: Response Getxtrendingcountries example: - buzz_score: 82.3 trend: stable mentions: 8934 unique_tickers: 156 unique_authors: 423 sentiment_score: 0.21 bullish_pct: 48 bearish_pct: 26 total_upvotes: 245000 trend_history: - 52.1 - 54.0 - 56.8 - 59.2 - 61.0 - 60.1 - 82.3 top_tickers: - NVDA - TSLA - AAPL - AMD - PLTR country: United States headers: X-Request-ID: description: Request correlation identifier returned by the API and included in structured application logs. schema: type: string example: adnos.req-20260423.abc12345 Cache-Control: description: HTTP cache policy returned by the API. schema: type: string example: private, max-age=300 Vary: description: Headers that private client caches must include in their cache key. schema: type: string example: X-API-Key, Authorization, Accept-Encoding X-RateLimit-Limit-Monthly: description: Monthly request quota for the authenticated account. schema: type: string example: '250' X-RateLimit-Remaining-Monthly: description: Remaining monthly requests for the authenticated account. schema: type: string example: '247' X-RateLimit-Used-Monthly: description: Requests already consumed in the account's current monthly quota window. schema: type: string example: '3' X-RateLimit-Reset-Monthly: description: ISO 8601 timestamp when the current monthly quota window resets. schema: type: string format: date-time example: '2026-07-29T14:03:00Z' X-RateLimit-Limit-Burst: description: Per-minute burst request quota for the authenticated account. schema: type: string example: '100' X-RateLimit-Remaining-Burst: description: Remaining requests in the current per-minute burst window. schema: type: string example: '99' X-RateLimit-Reset-Burst: description: ISO 8601 timestamp when the current burst rate-limit window resets. schema: type: string format: date-time example: '2026-04-28T14:30:00Z' X-Account-Type: description: Account tier resolved from the API key. schema: type: string enum: - free - hobby - professional - premium example: free '401': description: Authentication failed content: application/json: examples: missing: summary: Missing API key value: detail: Missing API key. Include 'X-API-Key' header. invalid: summary: Invalid API key value: detail: Invalid API key. revoked: summary: Revoked API key value: detail: API key has been revoked. schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Historical data limit exceeded content: application/json: example: detail: error: Historical data limit exceeded message: 'Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing' requested_days: 60 enforced_quantity: lookback_days max_days: 30 account_type: free schema: $ref: '#/components/schemas/HistoricalLimitError' '429': description: Rate limit exceeded content: application/json: examples: burst: summary: Fleet burst limit exceeded value: detail: error: Burst rate limit exceeded message: Too many requests. Limit is 100 requests per minute. limit: 100 used: 100 account_type: free local: summary: Local backup limiter exceeded value: detail: error: Rate limit exceeded message: 'Rate limit exceeded: 100 per 1 minute' limit: 100 account_type: free schema: $ref: '#/components/schemas/RateLimitError' '422': description: Invalid period or query parameters content: application/json: examples: platform_availability: summary: Period starts before platform data availability value: detail: error: Invalid period message: Requested period starts before this platform's public data availability. period_from: '2025-03-17' available_since: '2026-03-07' platform: news validation: summary: Query parameter validation failed value: detail: - type: greater_than_equal loc: - query - days msg: Input should be greater than or equal to 1 input: '0' ctx: ge: 1 schema: anyOf: - $ref: '#/components/schemas/InvalidPeriodError' - $ref: '#/components/schemas/HTTPValidationError' title: Response 422 Getxtrendingcountries '503': description: Database temporarily unavailable content: application/json: example: detail: Database temporarily unavailable schema: $ref: '#/components/schemas/ErrorResponse' '504': description: Analytics request deadline exceeded content: application/json: example: detail: Request deadline exceeded schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: curl label: cURL source: "curl \"https://api.adanos.org/x/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\" \\\n -H \"X-API-Key: sk_live_your_key_here\"" - lang: javascript label: JavaScript source: "const response = await fetch(\"https://api.adanos.org/x/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\", {\n headers: {\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);" - lang: python label: Python source: "import requests\n\nresponse = requests.get(\n \"https://api.adanos.org/x/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\",\n headers={\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())" /x/stocks/v1/stock/{ticker}: get: tags: - X/Twitter Stocks summary: Stock Sentiment description: 'Returns detailed X/Twitter data for a specific ticker. **Includes:** - `buzz_score`: normalized X/Twitter activity score for the selected period - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement or Grok rank movement. For `from`/`to`, anchors at `to` (or now when `to` is today) - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals - `mentions`, `unique_tweets`, `total_upvotes`: volume and engagement signals - `daily_trend`: daily X/Twitter activity and sentiment values - `top_tweets`: representative high-engagement tweets from the selected period Returns `200` with `found: false` when the ticker is supported but this service has no qualifying data in the requested window. Returns `404` only when the ticker is unsupported.' operationId: getXStockSentiment security: - ApiKeyAuth: [] parameters: - name: ticker in: path required: true schema: type: string pattern: ^\$?(?:[A-Za-z0-9]{1,8}[.-][A-Za-z]|[A-Za-z0-9]{0}[A-Za-z][A-Za-z0-9]{0,9}|[A-Za-z0-9]{1}[A-Za-z][A-Za-z0-9]{0,8}|[A-Za-z0-9]{2}[A-Za-z][A-Za-z0-9]{0,7}|[A-Za-z0-9]{3}[A-Za-z][A-Za-z0-9]{0,6}|[A-Za-z0-9]{4}[A-Za-z][A-Za-z0-9]{0,5}|[A-Za-z0-9]{5}[A-Za-z][A-Za-z0-9]{0,4}|[A-Za-z0-9]{6}[A-Za-z][A-Za-z0-9]{0,3}|[A-Za-z0-9]{7}[A-Za-z][A-Za-z0-9]{0,2}|[A-Za-z0-9]{8}[A-Za-z][A-Za-z0-9]{0,1}|[A-Za-z0-9]{9}[A-Za-z][A-Za-z0-9]{0,0}|[0-9]{3,10})$ description: Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A) examples: - TSLA title: Ticker description: Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A) - name: from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: Start date in YYYY-MM-DD. Inclusive UTC date. title: From description: Start date in YYYY-MM-DD. Inclusive UTC date. - name: to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. title: To description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. - name: days in: query required: false schema: type: integer maximum: 365 minimum: 1 description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. title: Days description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. deprecated: true x-adanos-hide-in-request-client: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/XStockDetailResponse' example: ticker: TSLA company_name: Tesla, Inc. found: true buzz_score: 72.5 mentions: 156 sentiment_score: 0.35 total_upvotes: 2847 unique_tweets: 42 trend: rising bullish_pct: 45 bearish_pct: 12 period_days: 7 daily_trend: - date: '2025-12-28' mentions: 42 sentiment_score: 0.15 buzz_score: 52.3 bullish_pct: 60 bearish_pct: 25 - date: '2025-12-27' mentions: 38 sentiment_score: 0.22 buzz_score: 48.1 bullish_pct: 55 bearish_pct: 18 top_tweets: - text_snippet: $TSLA breaking out! 🚀 sentiment_score: 0.85 sentiment_label: positive likes: 1247 retweets: 89 views: 52340 author: stockguru created_at: '2025-12-28T14:32:00Z' top_authors: - author: stockguru mentions: 24 sentiment_score: 0.41 buzz_score: 61.8 count: 24 headers: X-Request-ID: description: Request correlation identifier returned by the API and included in structured application logs. schema: type: string example: adnos.req-20260423.abc12345 Cache-Control: description: HTTP cache policy returned by the API. schema: type: string example: private, max-age=30 Vary: description: Headers that private client caches must include in their cache key. schema: type: string example: X-API-Key, Authorization, Accept-Encoding X-RateLimit-Limit-Monthly: description: Monthly request quota for the authenticated account. schema: type: string example: '250' X-RateLimit-Remaining-Monthly: description: Remaining monthly requests for the authenticated account. schema: type: string example: '247' X-RateLimit-Used-Monthly: description: Requests already consumed in the account's current monthly quota window. schema: type: string example: '3' X-RateLimit-Reset-Monthly: description: ISO 8601 timestamp when the current monthly quota window resets. schema: type: string format: date-time example: '2026-07-29T14:03:00Z' X-RateLimit-Limit-Burst: description: Per-minute burst request quota for the authenticated account. schema: type: string example: '100' X-RateLimit-Remaining-Burst: description: Remaining requests in the current per-minute burst window. schema: type: string example: '99' X-RateLimit-Reset-Burst: description: ISO 8601 timestamp when the current burst rate-limit window resets. schema: type: string format: date-time example: '2026-04-28T14:30:00Z' X-Account-Type: description: Account tier resolved from the API key. schema: type: string enum: - free - hobby - professional - premium example: free '401': description: Authentication failed content: application/json: examples: missing: summary: Missing API key value: detail: Missing API key. Include 'X-API-Key' header. invalid: summary: Invalid API key value: detail: Invalid API key. revoked: summary: Revoked API key value: detail: API key has been revoked. schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Historical data limit exceeded content: application/json: example: detail: error: Historical data limit exceeded message: 'Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing' requested_days: 60 enforced_quantity: lookback_days max_days: 30 account_type: free schema: $ref: '#/components/schemas/HistoricalLimitError' '429': description: Rate limit exceeded content: application/json: examples: burst: summary: Fleet burst limit exceeded value: detail: error: Burst rate limit exceeded message: Too many requests. Limit is 100 requests per minute. limit: 100 used: 100 account_type: free local: summary: Local backup limiter exceeded value: detail: error: Rate limit exceeded message: 'Rate limit exceeded: 100 per 1 minute' limit: 100 account_type: free schema: $ref: '#/components/schemas/RateLimitError' '422': description: Invalid period or query parameters content: application/json: examples: platform_availability: summary: Period starts before platform data availability value: detail: error: Invalid period message: Requested period starts before this platform's public data availability. period_from: '2025-03-17' available_since: '2026-03-07' platform: news validation: summary: Query parameter validation failed value: detail: - type: greater_than_equal loc: - query - days msg: Input should be greater than or equal to 1 input: '0' ctx: ge: 1 schema: anyOf: - $ref: '#/components/schemas/InvalidPeriodError' - $ref: '#/components/schemas/HTTPValidationError' title: Response 422 Getxstocksentiment '503': description: Database temporarily unavailable content: application/json: example: detail: Database temporarily unavailable schema: $ref: '#/components/schemas/ErrorResponse' '504': description: Analytics request deadline exceeded content: application/json: example: detail: Request deadline exceeded schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Unsupported ticker content: application/json: example: detail: error_code: unsupported_ticker message: Unsupported ticker $XYZ. This ticker is not supported by Adanos v1. schema: $ref: '#/components/schemas/UnsupportedAssetError' x-codeSamples: - lang: curl label: cURL source: "curl \"https://api.adanos.org/x/stocks/v1/stock/TSLA?from=2026-05-01&to=2026-05-07\" \\\n -H \"X-API-Key: sk_live_your_key_here\"" - lang: javascript label: JavaScript source: "const response = await fetch(\"https://api.adanos.org/x/stocks/v1/stock/TSLA?from=2026-05-01&to=2026-05-07\", {\n headers: {\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);" - lang: python label: Python source: "import requests\n\nresponse = requests.get(\n \"https://api.adanos.org/x/stocks/v1/stock/TSLA?from=2026-05-01&to=2026-05-07\",\n headers={\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())" /x/stocks/v1/market-sentiment: get: tags: - X/Twitter Stocks summary: Market Sentiment description: 'Returns the service-level X/Twitter market sentiment snapshot across all tracked stocks when you want a single X-wide market state instead of per-ticker rankings. It includes service-wide buzz, sentiment split, activity trend, breadth metrics and the top drivers by current `buzz_score`. `buzz_score` here means relative X/Twitter market heat, not pure bullishness. It measures how hot overall X stock discussion is versus X''s own trailing 90-day baseline: - around `50` = normal X market activity - higher = more active than usual - lower = quieter than usual `trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement or Grok rank movement. For `from`/`to`, anchors at `to` (or now when `to` is today). Use `sentiment_score`, `bullish_pct` and `bearish_pct` for direction.' operationId: getXMarketSentiment security: - ApiKeyAuth: [] parameters: - name: from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: Start date in YYYY-MM-DD. Inclusive UTC date. title: From description: Start date in YYYY-MM-DD. Inclusive UTC date. - name: to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. title: To description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. - name: days in: query required: false schema: type: integer maximum: 365 minimum: 1 description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. title: Days description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. deprecated: true x-adanos-hide-in-request-client: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/XMarketSentimentResponse' example: buzz_score: 56.2 trend: rising mentions: 2847 unique_tweets: 913 unique_authors: 604 total_upvotes: 28471 active_tickers: 442 sentiment_score: 0.081 positive_count: 1198 negative_count: 741 neutral_count: 908 bullish_pct: 42 bearish_pct: 26 trend_history: - 48.9 - 50.7 - 52.6 - 54.4 - 57.1 - 58.3 - 56.2 drivers: - ticker: TSLA mentions: 156 buzz_score: 72.5 sentiment_score: 0.35 - ticker: NVDA mentions: 141 buzz_score: 70.8 sentiment_score: 0.27 headers: X-Request-ID: description: Request correlation identifier returned by the API and included in structured application logs. schema: type: string example: adnos.req-20260423.abc12345 Cache-Control: description: HTTP cache policy returned by the API. schema: type: string example: private, max-age=300 Vary: description: Headers that private client caches must include in their cache key. schema: type: string example: X-API-Key, Authorization, Accept-Encoding X-RateLimit-Limit-Monthly: description: Monthly request quota for the authenticated account. schema: type: string example: '250' X-RateLimit-Remaining-Monthly: description: Remaining monthly requests for the authenticated account. schema: type: string example: '247' X-RateLimit-Used-Monthly: description: Requests already consumed in the account's current monthly quota window. schema: type: string example: '3' X-RateLimit-Reset-Monthly: description: ISO 8601 timestamp when the current monthly quota window resets. schema: type: string format: date-time example: '2026-07-29T14:03:00Z' X-RateLimit-Limit-Burst: description: Per-minute burst request quota for the authenticated account. schema: type: string example: '100' X-RateLimit-Remaining-Burst: description: Remaining requests in the current per-minute burst window. schema: type: string example: '99' X-RateLimit-Reset-Burst: description: ISO 8601 timestamp when the current burst rate-limit window resets. schema: type: string format: date-time example: '2026-04-28T14:30:00Z' X-Account-Type: description: Account tier resolved from the API key. schema: type: string enum: - free - hobby - professional - premium example: free '401': description: Authentication failed content: application/json: examples: missing: summary: Missing API key value: detail: Missing API key. Include 'X-API-Key' header. invalid: summary: Invalid API key value: detail: Invalid API key. revoked: summary: Revoked API key value: detail: API key has been revoked. schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Historical data limit exceeded content: application/json: example: detail: error: Historical data limit exceeded message: 'Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing' requested_days: 60 enforced_quantity: lookback_days max_days: 30 account_type: free schema: $ref: '#/components/schemas/HistoricalLimitError' '429': description: Rate limit exceeded content: application/json: examples: burst: summary: Fleet burst limit exceeded value: detail: error: Burst rate limit exceeded message: Too many requests. Limit is 100 requests per minute. limit: 100 used: 100 account_type: free local: summary: Local backup limiter exceeded value: detail: error: Rate limit exceeded message: 'Rate limit exceeded: 100 per 1 minute' limit: 100 account_type: free schema: $ref: '#/components/schemas/RateLimitError' '422': description: Invalid period or query parameters content: application/json: examples: platform_availability: summary: Period starts before platform data availability value: detail: error: Invalid period message: Requested period starts before this platform's public data availability. period_from: '2025-03-17' available_since: '2026-03-07' platform: news validation: summary: Query parameter validation failed value: detail: - type: greater_than_equal loc: - query - days msg: Input should be greater than or equal to 1 input: '0' ctx: ge: 1 schema: anyOf: - $ref: '#/components/schemas/InvalidPeriodError' - $ref: '#/components/schemas/HTTPValidationError' title: Response 422 Getxmarketsentiment '503': description: Database temporarily unavailable content: application/json: example: detail: Database temporarily unavailable schema: $ref: '#/components/schemas/ErrorResponse' '504': description: Analytics request deadline exceeded content: application/json: example: detail: Request deadline exceeded schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: curl label: cURL source: "curl \"https://api.adanos.org/x/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\" \\\n -H \"X-API-Key: sk_live_your_key_here\"" - lang: javascript label: JavaScript source: "const response = await fetch(\"https://api.adanos.org/x/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\", {\n headers: {\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);" - lang: python label: Python source: "import requests\n\nresponse = requests.get(\n \"https://api.adanos.org/x/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\",\n headers={\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())" /x/stocks/v1/stock/{ticker}/explain: get: tags: - X/Twitter Stocks summary: AI explanation description: 'Returns an AI-generated explanation for why a stock is trending on X/Twitter, anchored to tweet evidence with other platforms used only as cross-check context. **Includes:** - `explanation`: 1-2 sentence summary of why the stock is trending - `cached`: whether this was served from cache - `generated_at`: when the explanation was generated - `model`: which LLM model generated the explanation' operationId: getXStockExplanation security: - ApiKeyAuth: [] parameters: - name: ticker in: path required: true schema: type: string pattern: ^\$?(?:[A-Za-z0-9]{1,8}[.-][A-Za-z]|[A-Za-z0-9]{0}[A-Za-z][A-Za-z0-9]{0,9}|[A-Za-z0-9]{1}[A-Za-z][A-Za-z0-9]{0,8}|[A-Za-z0-9]{2}[A-Za-z][A-Za-z0-9]{0,7}|[A-Za-z0-9]{3}[A-Za-z][A-Za-z0-9]{0,6}|[A-Za-z0-9]{4}[A-Za-z][A-Za-z0-9]{0,5}|[A-Za-z0-9]{5}[A-Za-z][A-Za-z0-9]{0,4}|[A-Za-z0-9]{6}[A-Za-z][A-Za-z0-9]{0,3}|[A-Za-z0-9]{7}[A-Za-z][A-Za-z0-9]{0,2}|[A-Za-z0-9]{8}[A-Za-z][A-Za-z0-9]{0,1}|[A-Za-z0-9]{9}[A-Za-z][A-Za-z0-9]{0,0}|[0-9]{3,10})$ description: Stock ticker symbol (e.g., TSLA, aapl, BRK.A, $GME) title: Ticker description: Stock ticker symbol (e.g., TSLA, aapl, BRK.A, $GME) responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/StockExplanationResponse' example: ticker: GME company_name: Gamestop Corporation - Class A explanation: GME is trending due to viral GameStop social media activity and large position posts on r/Superstonk. cached: true generated_at: '2026-01-13T14:30:00+00:00' model: meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo headers: X-Request-ID: description: Request correlation identifier returned by the API and included in structured application logs. schema: type: string example: adnos.req-20260423.abc12345 Cache-Control: description: HTTP cache policy returned by the API. schema: type: string example: private, max-age=60 Vary: description: Headers that private client caches must include in their cache key. schema: type: string example: X-API-Key, Authorization, Accept-Encoding X-RateLimit-Limit-Monthly: description: Monthly request quota for the authenticated account. schema: type: string example: '250' X-RateLimit-Remaining-Monthly: description: Remaining monthly requests for the authenticated account. schema: type: string example: '247' X-RateLimit-Used-Monthly: description: Requests already consumed in the account's current monthly quota window. schema: type: string example: '3' X-RateLimit-Reset-Monthly: description: ISO 8601 timestamp when the current monthly quota window resets. schema: type: string format: date-time example: '2026-07-29T14:03:00Z' X-RateLimit-Limit-Burst: description: Per-minute burst request quota for the authenticated account. schema: type: string example: '100' X-RateLimit-Remaining-Burst: description: Remaining requests in the current per-minute burst window. schema: type: string example: '99' X-RateLimit-Reset-Burst: description: ISO 8601 timestamp when the current burst rate-limit window resets. schema: type: string format: date-time example: '2026-04-28T14:30:00Z' X-Account-Type: description: Account tier resolved from the API key. schema: type: string enum: - free - hobby - professional - premium example: free '401': description: Authentication failed content: application/json: examples: missing: summary: Missing API key value: detail: Missing API key. Include 'X-API-Key' header. invalid: summary: Invalid API key value: detail: Invalid API key. revoked: summary: Revoked API key value: detail: API key has been revoked. schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Historical data limit exceeded content: application/json: example: detail: error: Historical data limit exceeded message: 'Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing' requested_days: 60 enforced_quantity: lookback_days max_days: 30 account_type: free schema: $ref: '#/components/schemas/HistoricalLimitError' '429': description: Rate limit exceeded content: application/json: examples: burst: summary: Fleet burst limit exceeded value: detail: error: Burst rate limit exceeded message: Too many requests. Limit is 100 requests per minute. limit: 100 used: 100 account_type: free local: summary: Local backup limiter exceeded value: detail: error: Rate limit exceeded message: 'Rate limit exceeded: 100 per 1 minute' limit: 100 account_type: free schema: $ref: '#/components/schemas/RateLimitError' '422': description: Invalid period or query parameters content: application/json: examples: platform_availability: summary: Period starts before platform data availability value: detail: error: Invalid period message: Requested period starts before this platform's public data availability. period_from: '2025-03-17' available_since: '2026-03-07' platform: news validation: summary: Query parameter validation failed value: detail: - type: greater_than_equal loc: - query - days msg: Input should be greater than or equal to 1 input: '0' ctx: ge: 1 schema: anyOf: - $ref: '#/components/schemas/InvalidPeriodError' - $ref: '#/components/schemas/HTTPValidationError' title: Response 422 Getxstockexplanation '503': description: Explanation or database service unavailable content: application/json: example: detail: Explanation service temporarily unavailable. Try again later. '504': description: Analytics request deadline exceeded content: application/json: example: detail: Request deadline exceeded schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found or no data available for the requested asset/window content: application/json: example: detail: No mentions found for $XYZ in the last 7 days. schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: curl label: cURL source: "curl \"https://api.adanos.org/x/stocks/v1/stock/TSLA/explain\" \\\n -H \"X-API-Key: sk_live_your_key_here\"" - lang: javascript label: JavaScript source: "const response = await fetch(\"https://api.adanos.org/x/stocks/v1/stock/TSLA/explain\", {\n headers: {\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);" - lang: python label: Python source: "import requests\n\nresponse = requests.get(\n \"https://api.adanos.org/x/stocks/v1/stock/TSLA/explain\",\n headers={\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())" /x/stocks/v1/compare: get: tags: - X/Twitter Stocks summary: Compare stocks description: 'Compare up to 10 stocks side by side using X/Twitter metrics over the same UTC calendar-day period. Use it when you already know the tickers and want a compact ranked table instead of full detail reports. Results are sorted by `buzz_score` descending and include `trend`, `trend_history`, `mentions`, `unique_tweets`, `sentiment_score`, `bullish_pct`, `bearish_pct` and `total_upvotes`. `trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement or Grok rank movement. For `from`/`to`, anchors at `to` (or now when `to` is today).' operationId: compareXStocks security: - ApiKeyAuth: [] parameters: - name: from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: Start date in YYYY-MM-DD. Inclusive UTC date. title: From description: Start date in YYYY-MM-DD. Inclusive UTC date. - name: to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. title: To description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. - name: days in: query required: false schema: type: integer maximum: 365 minimum: 1 description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. title: Days description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. deprecated: true x-adanos-hide-in-request-client: true - name: tickers in: query required: true schema: type: string description: Comma-separated list of ticker symbols (e.g., TSLA,NVDA,AMD) examples: - TSLA,NVDA,AMD title: Tickers description: Comma-separated list of ticker symbols (e.g., TSLA,NVDA,AMD) responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/XCompareResponse' example: period_days: 7 stocks: - ticker: TSLA company_name: Tesla, Inc. buzz_score: 72.5 trend: rising mentions: 156 unique_tweets: 42 sentiment_score: 0.35 bullish_pct: 45 bearish_pct: 12 total_upvotes: 2847 trend_history: - 45.2 - 48.1 - 52.3 - 55.0 - 58.2 - 61.5 - 72.5 headers: X-Request-ID: description: Request correlation identifier returned by the API and included in structured application logs. schema: type: string example: adnos.req-20260423.abc12345 Cache-Control: description: HTTP cache policy returned by the API. schema: type: string example: private, max-age=30 Vary: description: Headers that private client caches must include in their cache key. schema: type: string example: X-API-Key, Authorization, Accept-Encoding X-RateLimit-Limit-Monthly: description: Monthly request quota for the authenticated account. schema: type: string example: '250' X-RateLimit-Remaining-Monthly: description: Remaining monthly requests for the authenticated account. schema: type: string example: '247' X-RateLimit-Used-Monthly: description: Requests already consumed in the account's current monthly quota window. schema: type: string example: '3' X-RateLimit-Reset-Monthly: description: ISO 8601 timestamp when the current monthly quota window resets. schema: type: string format: date-time example: '2026-07-29T14:03:00Z' X-RateLimit-Limit-Burst: description: Per-minute burst request quota for the authenticated account. schema: type: string example: '100' X-RateLimit-Remaining-Burst: description: Remaining requests in the current per-minute burst window. schema: type: string example: '99' X-RateLimit-Reset-Burst: description: ISO 8601 timestamp when the current burst rate-limit window resets. schema: type: string format: date-time example: '2026-04-28T14:30:00Z' X-Account-Type: description: Account tier resolved from the API key. schema: type: string enum: - free - hobby - professional - premium example: free '401': description: Authentication failed content: application/json: examples: missing: summary: Missing API key value: detail: Missing API key. Include 'X-API-Key' header. invalid: summary: Invalid API key value: detail: Invalid API key. revoked: summary: Revoked API key value: detail: API key has been revoked. schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Historical data limit exceeded content: application/json: example: detail: error: Historical data limit exceeded message: 'Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing' requested_days: 60 enforced_quantity: lookback_days max_days: 30 account_type: free schema: $ref: '#/components/schemas/HistoricalLimitError' '429': description: Rate limit exceeded content: application/json: examples: burst: summary: Fleet burst limit exceeded value: detail: error: Burst rate limit exceeded message: Too many requests. Limit is 100 requests per minute. limit: 100 used: 100 account_type: free local: summary: Local backup limiter exceeded value: detail: error: Rate limit exceeded message: 'Rate limit exceeded: 100 per 1 minute' limit: 100 account_type: free schema: $ref: '#/components/schemas/RateLimitError' '422': description: Invalid period or query parameters content: application/json: examples: platform_availability: summary: Period starts before platform data availability value: detail: error: Invalid period message: Requested period starts before this platform's public data availability. period_from: '2025-03-17' available_since: '2026-03-07' platform: news validation: summary: Query parameter validation failed value: detail: - type: greater_than_equal loc: - query - days msg: Input should be greater than or equal to 1 input: '0' ctx: ge: 1 schema: anyOf: - $ref: '#/components/schemas/InvalidPeriodError' - $ref: '#/components/schemas/HTTPValidationError' title: Response 422 Comparexstocks '503': description: Database temporarily unavailable content: application/json: example: detail: Database temporarily unavailable schema: $ref: '#/components/schemas/ErrorResponse' '504': description: Analytics request deadline exceeded content: application/json: example: detail: Request deadline exceeded schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Invalid compare item list content: application/json: example: detail: error: too_many_tickers message: Maximum 10 tickers allowed. max_items: 10 item_name: ticker examples: too_many_tickers: summary: Too many tickers value: detail: error: too_many_tickers message: Maximum 10 tickers allowed. max_items: 10 item_name: ticker no_valid_tickers: summary: No valid tickers value: detail: error: no_valid_tickers message: At least one valid ticker is required. max_items: 10 item_name: ticker schema: $ref: '#/components/schemas/CompareLimitError' x-codeSamples: - lang: curl label: cURL source: "curl \"https://api.adanos.org/x/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\" \\\n -H \"X-API-Key: sk_live_your_key_here\"" - lang: javascript label: JavaScript source: "const response = await fetch(\"https://api.adanos.org/x/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\", {\n headers: {\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);" - lang: python label: Python source: "import requests\n\nresponse = requests.get(\n \"https://api.adanos.org/x/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\",\n headers={\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())" /x/stocks/v1/search: get: tags: - X/Twitter Stocks summary: Search stocks description: Search stocks by ticker, company name or alias in the X/Twitter universe. Results prioritize exact ticker matches first, then prefixes, then name/alias matches and include a compact `summary` block for the last 7 UTC calendar days. operationId: searchXStocks security: - ApiKeyAuth: [] parameters: - name: q in: query required: true schema: type: string minLength: 2 description: Search query (minimum 2 non-$ characters after trimming) examples: - tesla title: Q description: Search query (minimum 2 non-$ characters after trimming) - name: limit in: query required: false schema: type: integer maximum: 50 minimum: 1 description: Maximum number of results to return examples: - 20 default: 20 title: Limit description: Maximum number of results to return responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/XSearchResponse' example: query: tesla count: 1 period_days: 7 results: - ticker: TSLA name: Tesla Inc. type: Stock exchange: NASDAQ sector: Consumer Discretionary country: United States aliases: - Tesla - Elon summary: mentions: 156 buzz_score: 72.5 trend: rising sentiment_score: 0.35 headers: X-Request-ID: description: Request correlation identifier returned by the API and included in structured application logs. schema: type: string example: adnos.req-20260423.abc12345 Cache-Control: description: HTTP cache policy returned by the API. schema: type: string example: private, max-age=15 Vary: description: Headers that private client caches must include in their cache key. schema: type: string example: X-API-Key, Authorization, Accept-Encoding X-RateLimit-Limit-Monthly: description: Monthly request quota for the authenticated account. schema: type: string example: '250' X-RateLimit-Remaining-Monthly: description: Remaining monthly requests for the authenticated account. schema: type: string example: '247' X-RateLimit-Used-Monthly: description: Requests already consumed in the account's current monthly quota window. schema: type: string example: '3' X-RateLimit-Reset-Monthly: description: ISO 8601 timestamp when the current monthly quota window resets. schema: type: string format: date-time example: '2026-07-29T14:03:00Z' X-RateLimit-Limit-Burst: description: Per-minute burst request quota for the authenticated account. schema: type: string example: '100' X-RateLimit-Remaining-Burst: description: Remaining requests in the current per-minute burst window. schema: type: string example: '99' X-RateLimit-Reset-Burst: description: ISO 8601 timestamp when the current burst rate-limit window resets. schema: type: string format: date-time example: '2026-04-28T14:30:00Z' X-Account-Type: description: Account tier resolved from the API key. schema: type: string enum: - free - hobby - professional - premium example: free '401': description: Authentication failed content: application/json: examples: missing: summary: Missing API key value: detail: Missing API key. Include 'X-API-Key' header. invalid: summary: Invalid API key value: detail: Invalid API key. revoked: summary: Revoked API key value: detail: API key has been revoked. schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit exceeded content: application/json: examples: burst: summary: Fleet burst limit exceeded value: detail: error: Burst rate limit exceeded message: Too many requests. Limit is 100 requests per minute. limit: 100 used: 100 account_type: free local: summary: Local backup limiter exceeded value: detail: error: Rate limit exceeded message: 'Rate limit exceeded: 100 per 1 minute' limit: 100 account_type: free schema: $ref: '#/components/schemas/RateLimitError' '503': description: Database temporarily unavailable content: application/json: example: detail: Database temporarily unavailable schema: $ref: '#/components/schemas/ErrorResponse' '504': description: Analytics request deadline exceeded content: application/json: example: detail: Request deadline exceeded schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Invalid search query parameters content: application/json: examples: fixed_window: summary: Search endpoints use a fixed summary window value: detail: error: Invalid search parameters message: Search endpoints use a fixed last-7-UTC-calendar-day summary window. unsupported_parameters: - days normalized_query: summary: Search query is too short after normalization value: detail: Search query must contain at least 2 non-$ characters after trimming validation: summary: Query parameter validation failed value: detail: - type: string_too_short loc: - query - q msg: String should have at least 2 characters input: t ctx: min_length: 2 schema: anyOf: - $ref: '#/components/schemas/InvalidSearchParametersError' - $ref: '#/components/schemas/HTTPValidationError' title: Response 422 Searchxstocks x-codeSamples: - lang: curl label: cURL source: "curl \"https://api.adanos.org/x/stocks/v1/search?q=tesla&limit=5\" \\\n -H \"X-API-Key: sk_live_your_key_here\"" - lang: javascript label: JavaScript source: "const response = await fetch(\"https://api.adanos.org/x/stocks/v1/search?q=tesla&limit=5\", {\n headers: {\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);" - lang: python label: Python source: "import requests\n\nresponse = requests.get(\n \"https://api.adanos.org/x/stocks/v1/search?q=tesla&limit=5\",\n headers={\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())" /x/stocks/v1/stats: get: tags: - X/Twitter Stocks summary: Service statistics description: 'Returns high-level coverage and freshness metrics for the X/Twitter dataset. Includes: - total X mentions in the database - number of unique tickers with X mentions - today''s UTC X mention and distinct ticker counts - supported ticker count from the reference universe' operationId: getXStats responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/XStatsResponse' example: total_mentions: 935 unique_tickers: 100 mentions_today: 42 unique_tickers_today: 12 supported_tickers: 35000 headers: X-Request-ID: description: Request correlation identifier returned by the API and included in structured application logs. schema: type: string example: adnos.req-20260423.abc12345 Cache-Control: description: HTTP cache policy returned by the API. schema: type: string example: private, max-age=300 Vary: description: Headers that private client caches must include in their cache key. schema: type: string example: X-API-Key, Authorization, Accept-Encoding X-RateLimit-Limit-Monthly: description: Monthly request quota for the authenticated account. schema: type: string example: '250' X-RateLimit-Remaining-Monthly: description: Remaining monthly requests for the authenticated account. schema: type: string example: '247' X-RateLimit-Used-Monthly: description: Requests already consumed in the account's current monthly quota window. schema: type: string example: '3' X-RateLimit-Reset-Monthly: description: ISO 8601 timestamp when the current monthly quota window resets. schema: type: string format: date-time example: '2026-07-29T14:03:00Z' X-RateLimit-Limit-Burst: description: Per-minute burst request quota for the authenticated account. schema: type: string example: '100' X-RateLimit-Remaining-Burst: description: Remaining requests in the current per-minute burst window. schema: type: string example: '99' X-RateLimit-Reset-Burst: description: ISO 8601 timestamp when the current burst rate-limit window resets. schema: type: string format: date-time example: '2026-04-28T14:30:00Z' X-Account-Type: description: Account tier resolved from the API key. schema: type: string enum: - free - hobby - professional - premium example: free '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing: summary: Missing API key value: detail: Missing API key. Include 'X-API-Key' header. invalid: summary: Invalid API key value: detail: Invalid API key. revoked: summary: Revoked API key value: detail: API key has been revoked. '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/RateLimitError' examples: burst: summary: Fleet burst limit exceeded value: detail: error: Burst rate limit exceeded message: Too many requests. Limit is 100 requests per minute. limit: 100 used: 100 account_type: free local: summary: Local backup limiter exceeded value: detail: error: Rate limit exceeded message: 'Rate limit exceeded: 100 per 1 minute' limit: 100 account_type: free '503': description: Database temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Database temporarily unavailable '504': description: Analytics request deadline exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Request deadline exceeded security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: "curl \"https://api.adanos.org/x/stocks/v1/stats\" \\\n -H \"X-API-Key: sk_live_your_key_here\"" - lang: javascript label: JavaScript source: "const response = await fetch(\"https://api.adanos.org/x/stocks/v1/stats\", {\n headers: {\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);" - lang: python label: Python source: "import requests\n\nresponse = requests.get(\n \"https://api.adanos.org/x/stocks/v1/stats\",\n headers={\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())" /x/stocks/v1/stock/{ticker}/mentions: get: tags: - X/Twitter Stocks summary: Raw Mentions description: 'Returns raw tweet rows for a specific ticker within the live raw-data retention window. **Professional account required.** Free and Hobby accounts cannot use this endpoint. **Use this endpoint when you need:** - tweet-level snippets - original timestamps - engagement counters on the raw rows **Notes:** - Use `from` and `to` for explicit UTC date windows - Results are ordered newest first and support deterministic `offset` + `limit` pagination - empty result sets return `200` with `results=[]`' operationId: getXStockRawMentions security: - ApiKeyAuth: [] parameters: - name: ticker in: path required: true schema: type: string pattern: ^\$?(?:[A-Za-z0-9]{1,8}[.-][A-Za-z]|[A-Za-z0-9]{0}[A-Za-z][A-Za-z0-9]{0,9}|[A-Za-z0-9]{1}[A-Za-z][A-Za-z0-9]{0,8}|[A-Za-z0-9]{2}[A-Za-z][A-Za-z0-9]{0,7}|[A-Za-z0-9]{3}[A-Za-z][A-Za-z0-9]{0,6}|[A-Za-z0-9]{4}[A-Za-z][A-Za-z0-9]{0,5}|[A-Za-z0-9]{5}[A-Za-z][A-Za-z0-9]{0,4}|[A-Za-z0-9]{6}[A-Za-z][A-Za-z0-9]{0,3}|[A-Za-z0-9]{7}[A-Za-z][A-Za-z0-9]{0,2}|[A-Za-z0-9]{8}[A-Za-z][A-Za-z0-9]{0,1}|[A-Za-z0-9]{9}[A-Za-z][A-Za-z0-9]{0,0}|[0-9]{3,10})$ description: Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A) examples: - TSLA - BRK.A title: Ticker description: Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A) - name: from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: Start date in YYYY-MM-DD. Inclusive UTC date. title: From description: Start date in YYYY-MM-DD. Inclusive UTC date. - name: to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. title: To description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date. - name: days in: query required: false schema: type: integer maximum: 365 minimum: 1 description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. title: Days description: Deprecated v1 compatibility shorthand. Prefer `from` and `to` for reproducible UTC date windows. deprecated: true x-adanos-hide-in-request-client: true - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of raw tweet rows to return examples: - 50 default: 50 title: Limit description: Maximum number of raw tweet rows to return - name: offset in: query required: false schema: type: integer minimum: 0 description: Number of raw mention rows to skip for offset-based pagination. examples: - 0 default: 0 title: Offset description: Number of raw mention rows to skip for offset-based pagination. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/XRawMentionsResponse' example: ticker: NVDA period_days: 7 count: 1 results: - tweet_id: '1901234567890' author: marketwatcher text_snippet: $NVDA still has room after the pullback... created_utc: '2026-03-20T14:11:02Z' likes: 942 retweets: 88 views: 52110 is_reply: false sentiment_score: 0.44 sentiment_label: positive headers: X-Request-ID: description: Request correlation identifier returned by the API and included in structured application logs. schema: type: string example: adnos.req-20260423.abc12345 Cache-Control: description: HTTP cache policy returned by the API. schema: type: string example: private, max-age=60 Vary: description: Headers that private client caches must include in their cache key. schema: type: string example: X-API-Key, Authorization, Accept-Encoding X-RateLimit-Limit-Monthly: description: Monthly request quota for the authenticated account. schema: type: string example: '250' X-RateLimit-Remaining-Monthly: description: Remaining monthly requests for the authenticated account. schema: type: string example: '247' X-RateLimit-Used-Monthly: description: Requests already consumed in the account's current monthly quota window. schema: type: string example: '3' X-RateLimit-Reset-Monthly: description: ISO 8601 timestamp when the current monthly quota window resets. schema: type: string format: date-time example: '2026-07-29T14:03:00Z' X-RateLimit-Limit-Burst: description: Per-minute burst request quota for the authenticated account. schema: type: string example: '100' X-RateLimit-Remaining-Burst: description: Remaining requests in the current per-minute burst window. schema: type: string example: '99' X-RateLimit-Reset-Burst: description: ISO 8601 timestamp when the current burst rate-limit window resets. schema: type: string format: date-time example: '2026-04-28T14:30:00Z' X-Account-Type: description: Account tier resolved from the API key. schema: type: string enum: - free - hobby - professional - premium example: free '401': description: Authentication failed content: application/json: examples: missing: summary: Missing API key value: detail: Missing API key. Include 'X-API-Key' header. invalid: summary: Invalid API key value: detail: Invalid API key. revoked: summary: Revoked API key value: detail: API key has been revoked. schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Historical data limit exceeded content: application/json: example: detail: error: Historical data limit exceeded message: 'Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing' requested_days: 60 enforced_quantity: lookback_days max_days: 30 account_type: free schema: $ref: '#/components/schemas/HistoricalLimitError' '429': description: Rate limit exceeded content: application/json: examples: burst: summary: Fleet burst limit exceeded value: detail: error: Burst rate limit exceeded message: Too many requests. Limit is 100 requests per minute. limit: 100 used: 100 account_type: free local: summary: Local backup limiter exceeded value: detail: error: Rate limit exceeded message: 'Rate limit exceeded: 100 per 1 minute' limit: 100 account_type: free schema: $ref: '#/components/schemas/RateLimitError' '422': description: Invalid period or query parameters content: application/json: examples: platform_availability: summary: Period starts before platform data availability value: detail: error: Invalid period message: Requested period starts before this platform's public data availability. period_from: '2025-03-17' available_since: '2026-03-07' platform: news validation: summary: Query parameter validation failed value: detail: - type: greater_than_equal loc: - query - days msg: Input should be greater than or equal to 1 input: '0' ctx: ge: 1 schema: anyOf: - $ref: '#/components/schemas/InvalidPeriodError' - $ref: '#/components/schemas/HTTPValidationError' title: Response 422 Getxstockrawmentions '503': description: Database temporarily unavailable content: application/json: example: detail: Database temporarily unavailable schema: $ref: '#/components/schemas/ErrorResponse' '504': description: Analytics request deadline exceeded content: application/json: example: detail: Request deadline exceeded schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: curl label: cURL source: "curl \"https://api.adanos.org/x/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\" \\\n -H \"X-API-Key: sk_live_your_key_here\"" - lang: javascript label: JavaScript source: "const response = await fetch(\"https://api.adanos.org/x/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\", {\n headers: {\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);" - lang: python label: Python source: "import requests\n\nresponse = requests.get(\n \"https://api.adanos.org/x/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\",\n headers={\n \"X-API-Key\": \"sk_live_your_key_here\",\n },\n timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())" components: schemas: XSearchResponse: properties: query: type: string title: Query description: Original search query examples: - tesla count: type: integer title: Count description: Total number of matching results before the limit is applied examples: - 1 period_days: type: integer minimum: 1.0 title: Period Days description: Fixed lookback window used for each summary block examples: - 7 results: items: $ref: '#/components/schemas/XSearchResultItem' type: array title: Results description: Top matching stocks capped by the requested limit type: object required: - query - count - period_days - results title: XSearchResponse description: Search response for X/Twitter stocks. examples: - query: tesla count: 1 period_days: 7 results: - ticker: TSLA name: Tesla Inc. type: Stock exchange: NASDAQ sector: Consumer Discretionary country: United States aliases: - Tesla - Elon summary: mentions: 156 buzz_score: 72.5 trend: rising sentiment_score: 0.35 XTrendingCountry: properties: buzz_score: anyOf: - type: number maximum: 100.0 minimum: 0.0 - type: 'null' title: Buzz Score description: Aggregated Buzz Score (0-100) from X mentions examples: - 78.4 trend: type: string enum: - rising - falling - stable title: Trend description: Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement or Grok rank movement. For `from`/`to`, anchors at `to` (or now when `to` is today). examples: - rising mentions: type: integer title: Mentions description: Total tweet mentions examples: - 4523 unique_tickers: type: integer title: Unique Tickers description: Number of unique tickers mentioned examples: - 34 unique_authors: type: integer title: Unique Authors description: Exact distinct author breadth across the selected UTC period examples: - 156 sentiment_score: anyOf: - type: number maximum: 1.0 minimum: -1.0 - type: 'null' title: Sentiment Score description: Weighted average sentiment (-1 bearish to +1 bullish) examples: - 0.28 bullish_pct: anyOf: - type: integer maximum: 100.0 minimum: 0.0 - type: 'null' title: Bullish Pct description: Percentage of bullish mentions examples: - 54 bearish_pct: anyOf: - type: integer maximum: 100.0 minimum: 0.0 - type: 'null' title: Bearish Pct description: Percentage of bearish mentions examples: - 22 total_upvotes: anyOf: - type: integer - type: 'null' title: Total Upvotes description: Total likes across all mentions examples: - 128450 trend_history: items: type: number type: array title: Trend History description: Daily dimension buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values. Every slot describes only its UTC calendar day. The live final value describes today so far and can differ from period buzz_score. Closed historical windows end at `to`. Historical author breadth is rebuilt from daily author_distribution where available and may conservatively approximate exact cross-ticker author de-duplication. examples: - - 45.2 - 48.1 - 52.3 - 55.0 - 58.2 - 61.5 - 78.4 top_tickers: items: type: string type: array maxItems: 5 title: Top Tickers description: Top 5 tickers by mention count in this dimension examples: - - NVDA - AAPL - MSFT - AMD - GOOGL country: type: string title: Country description: Country name examples: - United States type: object required: - buzz_score - trend - mentions - unique_tickers - unique_authors - trend_history - top_tickers - country title: XTrendingCountry description: Trending country with aggregated buzz metrics from X/Twitter. examples: - buzz_score: 82.3 trend: stable mentions: 8934 unique_tickers: 156 unique_authors: 423 sentiment_score: 0.21 bullish_pct: 48 bearish_pct: 26 total_upvotes: 245000 trend_history: - 52.1 - 54.0 - 56.8 - 59.2 - 61.0 - 60.1 - 82.3 top_tickers: - NVDA - TSLA - AAPL - AMD - PLTR country: United States HistoricalLimitError: properties: detail: $ref: '#/components/schemas/HistoricalLimitErrorDetail' description: Structured error details type: object required: - detail title: HistoricalLimitError description: Error response for historical data limit exceeded (HTTP 403). InvalidPeriodErrorDetail: properties: error: type: string title: Error description: Error type identifier message: type: string title: Message description: Human-readable error message field: anyOf: - type: string - type: 'null' title: Field description: Invalid query parameter name value: anyOf: - type: string - type: integer - type: 'null' title: Value description: Invalid query parameter value today: anyOf: - type: string format: date - type: 'null' title: Today description: Current UTC date used for validation period_from: anyOf: - type: string format: date - type: 'null' title: Period From description: Resolved inclusive UTC start date period_to: anyOf: - type: string format: date - type: 'null' title: Period To description: Resolved inclusive UTC end date available_since: anyOf: - type: string format: date - type: 'null' title: Available Since description: Earliest public data date for the platform retention_from: anyOf: - type: string format: date - type: 'null' title: Retention From description: Earliest date retained for the endpoint requested_days: anyOf: - type: integer - type: 'null' title: Requested Days description: Number of days requested max_days: anyOf: - type: integer - type: 'null' title: Max Days description: Maximum days accepted by the endpoint platform: anyOf: - type: string - type: 'null' title: Platform description: Platform identifier type: object required: - error - message title: InvalidPeriodErrorDetail description: Structured error detail for invalid period windows. XTrendingStock: properties: ticker: type: string title: Ticker description: Stock ticker symbol examples: - TSLA company_name: anyOf: - type: string - type: 'null' title: Company Name description: Company name from ticker_reference examples: - Tesla, Inc. buzz_score: anyOf: - type: number maximum: 100.0 minimum: 0.0 - type: 'null' title: Buzz Score description: 'V5.5 buzz score from real tweet data. Components: mentions (20), sentiment (20), quality (10), author diversity (14, HHI-based when author_distribution is available, else scaled unique_authors), trend (-10 to +20). Asymptotic scaling caps at 100.' examples: - 72.5 trend: type: string enum: - rising - falling - stable title: Trend description: Activity momentum over the current 3 UTC days vs previous 3 UTC days, not price movement or Grok rank movement. examples: - rising mentions: type: integer minimum: 0.0 title: Mentions description: Number of tweet mentions from x_mentions table examples: - 156 sentiment_score: anyOf: - type: number maximum: 1.0 minimum: -1.0 - type: 'null' title: Sentiment Score description: Average sentiment score from tweet analysis (-1 to +1) examples: - 0.35 bullish_pct: anyOf: - type: integer maximum: 100.0 minimum: 0.0 - type: 'null' title: Bullish Pct description: Percentage of bullish tweet mentions examples: - 45 bearish_pct: anyOf: - type: integer maximum: 100.0 minimum: 0.0 - type: 'null' title: Bearish Pct description: Percentage of bearish tweet mentions examples: - 12 total_upvotes: anyOf: - type: integer - type: 'null' title: Total Upvotes description: Total likes across all tweet mentions examples: - 2847 unique_tweets: anyOf: - type: integer - type: 'null' title: Unique Tweets description: Number of unique tweets mentioning this ticker (distinct tweet_id) examples: - 42 trend_history: items: type: number type: array title: Trend History description: Daily buzz scores (oldest→newest). Length follows the resolved period, with a minimum of 7 values. For live windows, the final value is the current live buzz_score; closed historical windows end at `to`. examples: - - 45.2 - 48.1 - 52.3 - 55.0 - 58.2 - 61.5 - 64.8 type: object required: - ticker - buzz_score - trend - mentions title: XTrendingStock description: 'Trending stock on X/Twitter - unified format matching Reddit API structure. V5.5: Uses real tweet data from x_mentions (collected via twscrape). Author diversity now prefers HHI-based effective authors from author_distribution and falls back to scaled unique_authors only when the full distribution is unavailable.' examples: - ticker: TSLA company_name: Tesla, Inc. buzz_score: 72.5 trend: rising mentions: 156 sentiment_score: 0.35 bullish_pct: 45 bearish_pct: 12 total_upvotes: 2847 unique_tweets: 42 trend_history: - 45.2 - 48.1 - 52.3 - 55.0 - 58.2 - 61.5 - 64.8 XMarketSentimentResponse: properties: buzz_score: anyOf: - type: number maximum: 100.0 minimum: 0.0 - type: 'null' title: Buzz Score description: Service-wide X/Twitter heat score relative to the service's trailing 90-day baseline. Around 50 = normal activity, higher values = hotter-than-usual X activity. examples: - 56.2 trend: anyOf: - type: string enum: - rising - falling - stable - type: 'null' title: Trend description: Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement or Grok rank movement. For `from`/`to`, anchors at `to` (or now when `to` is today). examples: - rising mentions: type: integer minimum: 0.0 title: Mentions description: Tweet mentions across the selected period examples: - 2847 unique_tweets: type: integer minimum: 0.0 title: Unique Tweets description: Exact distinct tweet count across the selected UTC period examples: - 913 unique_authors: type: integer minimum: 0.0 title: Unique Authors description: Exact distinct author breadth across the selected UTC period examples: - 604 total_upvotes: type: integer minimum: 0.0 title: Total Upvotes description: Total likes across the selected period examples: - 28471 active_tickers: type: integer minimum: 0.0 title: Active Tickers description: Number of tickers with X activity in the selected period examples: - 442 sentiment_score: anyOf: - type: number maximum: 1.0 minimum: -1.0 - type: 'null' title: Sentiment Score description: Service-wide average tweet sentiment score examples: - 0.081 positive_count: type: integer minimum: 0.0 title: Positive Count description: Deprecated. Prefer bullish_pct with mentions for public analysis; retained for v1 compatibility. deprecated: true examples: - 1198 negative_count: type: integer minimum: 0.0 title: Negative Count description: Deprecated. Prefer bearish_pct with mentions for public analysis; retained for v1 compatibility. deprecated: true examples: - 741 neutral_count: type: integer minimum: 0.0 title: Neutral Count description: Deprecated. Prefer bullish_pct, bearish_pct and mentions for public analysis; retained for v1 compatibility. deprecated: true examples: - 908 bullish_pct: type: integer maximum: 100.0 minimum: 0.0 title: Bullish Pct description: Bullish tweet percentage examples: - 42 bearish_pct: type: integer maximum: 100.0 minimum: 0.0 title: Bearish Pct description: Bearish tweet percentage examples: - 26 trend_history: items: type: number type: array title: Trend History description: Daily service-wide buzz scores (oldest→newest) using the same relative baseline calibration. Length = max(requested_days, 7) for successful requests; windows before platform availability return HTTP 422. examples: - - 48.9 - 50.7 - 52.6 - 54.4 - 57.1 - 58.3 - 56.2 drivers: items: $ref: '#/components/schemas/XMarketSentimentDriver' type: array title: Drivers description: Top assets by current buzz_score driving the service-level reading type: object required: - buzz_score - mentions - unique_tweets - unique_authors - total_upvotes - active_tickers - positive_count - negative_count - neutral_count - bullish_pct - bearish_pct title: XMarketSentimentResponse description: Service-level X/Twitter market sentiment across all tracked stocks. examples: - buzz_score: 56.2 trend: rising mentions: 2847 unique_tweets: 913 unique_authors: 604 total_upvotes: 28471 active_tickers: 442 sentiment_score: 0.081 positive_count: 1198 negative_count: 741 neutral_count: 908 bullish_pct: 42 bearish_pct: 26 trend_history: - 48.9 - 50.7 - 52.6 - 54.4 - 57.1 - 58.3 - 56.2 drivers: - ticker: TSLA mentions: 156 buzz_score: 72.5 sentiment_score: 0.35 - ticker: NVDA mentions: 141 buzz_score: 70.8 sentiment_score: 0.27 XMarketSentimentDriver: properties: ticker: type: string title: Ticker description: Stock ticker symbol examples: - TSLA mentions: type: integer minimum: 0.0 title: Mentions description: Tweet mentions in the selected period examples: - 156 buzz_score: anyOf: - type: number maximum: 100.0 minimum: 0.0 - type: 'null' title: Buzz Score description: Asset buzz score in the selected period examples: - 72.5 sentiment_score: anyOf: - type: number maximum: 1.0 minimum: -1.0 - type: 'null' title: Sentiment Score description: Average tweet sentiment score for this asset examples: - 0.35 type: object required: - ticker - mentions - buzz_score title: XMarketSentimentDriver description: Top asset contributing to the service-level X market sentiment. UnsupportedAssetError: properties: detail: $ref: '#/components/schemas/UnsupportedAssetErrorDetail' description: Structured unsupported asset details type: object required: - detail title: UnsupportedAssetError description: Error response for unsupported v1 stock/crypto asset requests. InvalidSearchParametersErrorDetail: properties: error: type: string title: Error description: Error type identifier message: type: string title: Message description: Human-readable error message unsupported_parameters: items: type: string type: array title: Unsupported Parameters description: Search query parameters that are not supported type: object required: - error - message - unsupported_parameters title: InvalidSearchParametersErrorDetail description: Structured error detail for unsupported search query parameters. XRawMentionsResponse: properties: ticker: type: string title: Ticker description: Stock ticker symbol examples: - NVDA period_days: type: integer minimum: 1.0 title: Period Days description: Lookback window used for the query examples: - 7 count: type: integer minimum: 0.0 title: Count description: Total number of matching raw rows before limit and offset are applied; only the requested page is returned examples: - 1 results: items: $ref: '#/components/schemas/XRawMentionItem' type: array title: Results description: Raw tweet rows ordered by newest first type: object required: - ticker - period_days - count - results title: XRawMentionsResponse description: Paginated raw tweet mentions for a single stock ticker. examples: - ticker: NVDA period_days: 7 count: 1 results: - tweet_id: '1901234567890' author: marketwatcher text_snippet: $NVDA still has room after the pullback... created_utc: '2026-03-20T14:11:02Z' likes: 942 retweets: 88 views: 52110 is_reply: false sentiment_score: 0.44 sentiment_label: positive HistoricalLimitErrorDetail: properties: error: type: string title: Error description: Error type identifier message: type: string title: Message description: Human-readable error message requested_days: type: integer title: Requested Days description: Number of days requested enforced_quantity: anyOf: - type: string - type: 'null' title: Enforced Quantity description: Quantity checked against the account tier limit max_days: type: integer title: Max Days description: Maximum days allowed for account tier account_type: type: string title: Account Type description: User's account type (free, hobby, professional, premium) type: object required: - error - message - requested_days - max_days - account_type title: HistoricalLimitErrorDetail description: Structured error detail for historical data limit exceeded. XSearchResultItem: properties: ticker: type: string title: Ticker description: Stock ticker symbol examples: - TSLA name: type: string title: Name description: Company name examples: - Tesla Inc. type: anyOf: - type: string - type: 'null' title: Type description: Asset type (Stock, ETF, etc.) examples: - Stock exchange: anyOf: - type: string - type: 'null' title: Exchange description: Stock exchange examples: - NASDAQ sector: anyOf: - type: string - type: 'null' title: Sector description: Industry sector examples: - Consumer Discretionary country: anyOf: - type: string - type: 'null' title: Country description: Country of headquarters examples: - United States aliases: items: type: string type: array title: Aliases description: Alternative names/aliases examples: - - Tesla - Elon summary: $ref: '#/components/schemas/XSearchSummary' description: Last-7-days X summary for this asset type: object required: - ticker - name - summary title: XSearchResultItem description: Individual X/Twitter search result item. XCompareResponse: properties: period_days: type: integer title: Period Days description: Analysis period in days examples: - 7 stocks: items: $ref: '#/components/schemas/XCompareStockItem' type: array title: Stocks description: Stocks sorted by buzz_score descending type: object required: - period_days - stocks title: XCompareResponse description: Comparison response for multiple X/Twitter stocks. examples: - period_days: 7 stocks: - ticker: TSLA company_name: Tesla, Inc. buzz_score: 72.5 trend: rising mentions: 156 unique_tweets: 42 sentiment_score: 0.35 bullish_pct: 45 bearish_pct: 12 total_upvotes: 2847 trend_history: - 45.2 - 48.1 - 52.3 - 55.0 - 58.2 - 61.5 - 72.5 CompareLimitErrorDetail: properties: error: type: string title: Error description: Machine-readable error code message: type: string title: Message description: Human-readable error message max_items: type: integer title: Max Items description: Maximum accepted compare items item_name: type: string title: Item Name description: Compared item type, such as ticker or symbol type: object required: - error - message - max_items - item_name title: CompareLimitErrorDetail description: Structured error detail for compare item-count violations. XSearchSummary: properties: mentions: type: integer minimum: 0.0 title: Mentions description: Tweet mentions in the last 7 UTC calendar days examples: - 156 buzz_score: anyOf: - type: number maximum: 100.0 minimum: 0.0 - type: 'null' title: Buzz Score description: Buzz score over the last 7 UTC calendar days examples: - 72.5 trend: anyOf: - type: string enum: - rising - falling - stable - type: 'null' title: Trend description: Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement or Grok rank movement. For `from`/`to`, anchors at `to` (or now when `to` is today). examples: - rising sentiment_score: anyOf: - type: number maximum: 1.0 minimum: -1.0 - type: 'null' title: Sentiment Score description: Average sentiment score over the last 7 UTC calendar days examples: - 0.35 type: object required: - mentions - buzz_score title: XSearchSummary description: Compact last-7-days summary attached to X search results. XStatsResponse: properties: total_mentions: type: integer title: Total Mentions description: Rollup-backed all-time X mention total; current-day raw rows may be used only as a bounded freshness fallback default: 0 unique_tickers: type: integer title: Unique Tickers description: Number of unique tickers with X mentions in the database default: 0 mentions_today: type: integer title: Mentions Today description: X mention rows created since today's UTC midnight default: 0 unique_tickers_today: type: integer title: Unique Tickers Today description: Unique tickers with X mentions since today's UTC midnight default: 0 supported_tickers: type: integer title: Supported Tickers description: Total tickers in ticker_reference table default: 0 type: object title: XStatsResponse description: X/Twitter service statistics. examples: - total_mentions: 935 unique_tickers: 100 mentions_today: 42 unique_tickers_today: 12 supported_tickers: 35000 CompareLimitError: properties: detail: $ref: '#/components/schemas/CompareLimitErrorDetail' description: Structured error details type: object required: - detail title: CompareLimitError description: Error response for compare item-count violations (HTTP 400). XTopAuthor: properties: author: type: string title: Author description: Public X/Twitter username examples: - marketwatcher mentions: type: integer minimum: 0.0 title: Mentions description: Tweet mentions by this author in the selected period examples: - 72 sentiment_score: anyOf: - type: number maximum: 1.0 minimum: -1.0 - type: 'null' title: Sentiment Score description: Average sentiment score for this author's mentions in the selected period examples: - 0.18 buzz_score: anyOf: - type: number maximum: 100.0 minimum: 0.0 - type: 'null' title: Buzz Score description: Contributor-level buzz score for this author in the selected period examples: - 67.3 count: type: integer minimum: 0.0 title: Count description: Deprecated alias for mentions. Use mentions instead. deprecated: true examples: - 72 type: object required: - author - mentions - count title: XTopAuthor description: X author contributor metrics for a stock detail response. XTrendingSector: properties: buzz_score: anyOf: - type: number maximum: 100.0 minimum: 0.0 - type: 'null' title: Buzz Score description: Aggregated Buzz Score (0-100) from X mentions examples: - 78.4 trend: type: string enum: - rising - falling - stable title: Trend description: Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement or Grok rank movement. For `from`/`to`, anchors at `to` (or now when `to` is today). examples: - rising mentions: type: integer title: Mentions description: Total tweet mentions examples: - 4523 unique_tickers: type: integer title: Unique Tickers description: Number of unique tickers mentioned examples: - 34 unique_authors: type: integer title: Unique Authors description: Exact distinct author breadth across the selected UTC period examples: - 156 sentiment_score: anyOf: - type: number maximum: 1.0 minimum: -1.0 - type: 'null' title: Sentiment Score description: Weighted average sentiment (-1 bearish to +1 bullish) examples: - 0.28 bullish_pct: anyOf: - type: integer maximum: 100.0 minimum: 0.0 - type: 'null' title: Bullish Pct description: Percentage of bullish mentions examples: - 54 bearish_pct: anyOf: - type: integer maximum: 100.0 minimum: 0.0 - type: 'null' title: Bearish Pct description: Percentage of bearish mentions examples: - 22 total_upvotes: anyOf: - type: integer - type: 'null' title: Total Upvotes description: Total likes across all mentions examples: - 128450 trend_history: items: type: number type: array title: Trend History description: Daily dimension buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values. Every slot describes only its UTC calendar day. The live final value describes today so far and can differ from period buzz_score. Closed historical windows end at `to`. Historical author breadth is rebuilt from daily author_distribution where available and may conservatively approximate exact cross-ticker author de-duplication. examples: - - 45.2 - 48.1 - 52.3 - 55.0 - 58.2 - 61.5 - 78.4 top_tickers: items: type: string type: array maxItems: 5 title: Top Tickers description: Top 5 tickers by mention count in this dimension examples: - - NVDA - AAPL - MSFT - AMD - GOOGL sector: type: string title: Sector description: Industry sector name examples: - Technology type: object required: - buzz_score - trend - mentions - unique_tickers - unique_authors - trend_history - top_tickers - sector title: XTrendingSector description: Trending sector with aggregated buzz metrics from X/Twitter. examples: - buzz_score: 78.4 trend: rising mentions: 4523 unique_tickers: 34 unique_authors: 156 sentiment_score: 0.28 bullish_pct: 54 bearish_pct: 22 total_upvotes: 128450 trend_history: - 45.2 - 48.1 - 52.3 - 55.0 - 58.2 - 61.5 - 78.4 top_tickers: - NVDA - AAPL - MSFT - AMD - GOOGL sector: Technology HTTPValidationError: properties: detail: anyOf: - items: $ref: '#/components/schemas/ValidationError' type: array - type: 'null' title: Detail description: Validation error details type: object title: HTTPValidationError description: FastAPI/Pydantic validation error response. examples: - detail: - loc: - query - days msg: Input should be greater than or equal to 1 type: greater_than_equal RateLimitErrorDetail: properties: error: type: string title: Error description: Error type identifier message: type: string title: Message description: Human-readable error message limit: anyOf: - type: integer - type: 'null' title: Limit description: Applied request limit for the window used: anyOf: - type: integer - type: 'null' title: Used description: Requests used in the current window remaining: anyOf: - type: integer - type: 'null' title: Remaining description: Requests remaining in the current window account_type: type: string title: Account Type description: Resolved account type or fallback tier reset_at: anyOf: - type: string format: date-time - type: 'null' title: Reset At description: ISO 8601 timestamp when the current window resets contact: anyOf: - type: string - type: 'null' title: Contact description: Plan or support URL for resolving the limit type: object required: - error - message - account_type title: RateLimitErrorDetail description: Structured rate-limit error detail. StockExplanationResponse: properties: ticker: type: string title: Ticker description: Stock ticker symbol examples: - GME company_name: anyOf: - type: string - type: 'null' title: Company Name description: Company name from ticker_reference examples: - Gamestop Corporation - Class A explanation: type: string title: Explanation description: AI-generated explanation of why this stock is trending examples: - GME is trending due to viral GameStop social media activity and large position posts on r/Superstonk. cached: type: boolean title: Cached description: Whether the explanation was served from cache examples: - true generated_at: type: string title: Generated At description: Timezone-aware UTC ISO timestamp when explanation was generated examples: - '2026-01-13T14:30:00+00:00' model: anyOf: - type: string - type: 'null' title: Model description: LLM model used for generation examples: - meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo type: object required: - ticker - explanation - cached - generated_at title: StockExplanationResponse description: AI-generated trend explanation for a stock. examples: - ticker: GME company_name: Gamestop Corporation - Class A explanation: GME is trending due to viral GameStop social media activity and large position posts on r/Superstonk. cached: true generated_at: '2026-01-13T14:30:00+00:00' model: meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo RateLimitError: properties: detail: $ref: '#/components/schemas/RateLimitErrorDetail' description: Structured rate-limit details type: object required: - detail title: RateLimitError description: Error response for rate-limit exceeded responses. InvalidPeriodError: properties: detail: $ref: '#/components/schemas/InvalidPeriodErrorDetail' description: Structured error details type: object required: - detail title: InvalidPeriodError description: Error response for invalid period requests (HTTP 422). XStockDetailResponse: properties: ticker: type: string title: Ticker description: Stock ticker symbol company_name: anyOf: - type: string - type: 'null' title: Company Name description: Company name from ticker_reference found: type: boolean title: Found description: Legacy v1 data-availability flag. `true` means this service has qualifying data for this asset/window. `false` means the asset is supported, but this service has no qualifying data for the requested window. Planned for removal in v2. default: true deprecated: true buzz_score: anyOf: - type: number maximum: 100.0 minimum: 0.0 - type: 'null' title: Buzz Score description: V5.5 buzz score from real tweet data using HHI-based author diversity when author_distribution is available, else scaled unique_authors (null if not found) mentions: anyOf: - type: integer - type: 'null' title: Mentions description: Total tweet mentions within the selected period examples: - 156 sentiment_score: anyOf: - type: number maximum: 1.0 minimum: -1.0 - type: 'null' title: Sentiment Score description: Average sentiment score from tweet analysis (-1 to +1) positive_count: anyOf: - type: integer - type: 'null' title: Positive Count description: Deprecated. Prefer bullish_pct with mentions for public analysis; retained for v1 compatibility. deprecated: true negative_count: anyOf: - type: integer - type: 'null' title: Negative Count description: Deprecated. Prefer bearish_pct with mentions for public analysis; retained for v1 compatibility. deprecated: true neutral_count: anyOf: - type: integer - type: 'null' title: Neutral Count description: Deprecated. Prefer bullish_pct, bearish_pct and mentions for public analysis; retained for v1 compatibility. deprecated: true total_upvotes: anyOf: - type: integer - type: 'null' title: Total Upvotes description: Total likes across all tweet mentions unique_tweets: anyOf: - type: integer - type: 'null' title: Unique Tweets description: Number of unique tweets (distinct tweet_id) trend: anyOf: - type: string enum: - rising - falling - stable - type: 'null' title: Trend description: Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement or Grok rank movement. For `from`/`to`, anchors at `to` (or now when `to` is today). examples: - rising bullish_pct: anyOf: - type: integer maximum: 100.0 minimum: 0.0 - type: 'null' title: Bullish Pct description: Percentage of bullish tweet mentions examples: - 45 bearish_pct: anyOf: - type: integer maximum: 100.0 minimum: 0.0 - type: 'null' title: Bearish Pct description: Percentage of bearish tweet mentions examples: - 12 period_days: anyOf: - type: integer - type: 'null' title: Period Days description: Analysis period in days daily_trend: anyOf: - items: $ref: '#/components/schemas/XDailyTrendItem' type: array - type: 'null' title: Daily Trend description: Daily mention breakdown for the selected period top_tweets: anyOf: - items: $ref: '#/components/schemas/XTopTweet' type: array maxItems: 10 - type: 'null' title: Top Tweets description: Top tweets from the selected period, ranked by engagement (likes + retweets) top_authors: anyOf: - items: $ref: '#/components/schemas/XTopAuthor' type: array maxItems: 5 - type: 'null' title: Top Authors description: Top X authors in the selected period with mentions, sentiment_score, buzz_score and deprecated count alias type: object required: - ticker title: XStockDetailResponse description: 'Detailed X/Twitter data for a single stock - unified format matching Reddit API. V5.5: Uses real tweet data from x_mentions table with HHI-based effective author diversity when author_distribution is available.' examples: - ticker: TSLA company_name: Tesla, Inc. found: true buzz_score: 72.5 mentions: 156 sentiment_score: 0.35 total_upvotes: 2847 unique_tweets: 42 trend: rising bullish_pct: 45 bearish_pct: 12 period_days: 7 daily_trend: - date: '2025-12-28' mentions: 42 sentiment_score: 0.15 buzz_score: 52.3 bullish_pct: 60 bearish_pct: 25 - date: '2025-12-27' mentions: 38 sentiment_score: 0.22 buzz_score: 48.1 bullish_pct: 55 bearish_pct: 18 top_tweets: - text_snippet: $TSLA breaking out! 🚀 sentiment_score: 0.85 sentiment_label: positive likes: 1247 retweets: 89 views: 52340 author: stockguru created_at: '2025-12-28T14:32:00Z' top_authors: - author: stockguru mentions: 24 sentiment_score: 0.41 buzz_score: 61.8 count: 24 XRawMentionItem: properties: tweet_id: type: string title: Tweet Id description: Tweet identifier examples: - '1901234567890' author: anyOf: - type: string - type: 'null' title: Author description: Public X/Twitter username, if scraped examples: - marketwatcher text_snippet: type: string maxLength: 280 title: Text Snippet description: Tweet text snippet examples: - $NVDA still has room after the pullback... created_utc: anyOf: - type: string format: date-time - type: 'null' title: Created Utc description: Tweet creation time (ISO 8601) when available examples: - '2026-03-20T14:11:02Z' likes: type: integer minimum: 0.0 title: Likes description: Number of likes examples: - 942 retweets: type: integer minimum: 0.0 title: Retweets description: Number of retweets examples: - 88 views: anyOf: - type: integer minimum: 0.0 - type: 'null' title: Views description: Number of views examples: - 52110 is_reply: type: boolean title: Is Reply description: Whether this row comes from a reply tweet examples: - false parent_tweet_id: anyOf: - type: string - type: 'null' title: Parent Tweet Id description: Parent tweet identifier for replies examples: - '1900000000000' sentiment_score: anyOf: - type: number maximum: 1.0 minimum: -1.0 - type: 'null' title: Sentiment Score description: Sentiment score (-1 to +1) examples: - 0.44 sentiment_label: anyOf: - type: string - type: 'null' title: Sentiment Label description: Sentiment label (positive/negative/neutral) examples: - positive type: object required: - tweet_id - text_snippet - likes - retweets - is_reply title: XRawMentionItem description: Raw tweet mention row for one stock ticker. XDailyTrendItem: properties: date: type: string title: Date description: Date in YYYY-MM-DD format examples: - '2025-12-28' mentions: type: integer title: Mentions description: Number of tweet mentions on this date examples: - 42 sentiment_score: anyOf: - type: number maximum: 1.0 minimum: -1.0 - type: 'null' title: Sentiment Score description: Average sentiment score for the day examples: - 0.15 buzz_score: anyOf: - type: number maximum: 100.0 minimum: 0.0 - type: 'null' title: Buzz Score description: Buzz score for this date (0-100) examples: - 52.3 bullish_pct: anyOf: - type: integer maximum: 100.0 minimum: 0.0 - type: 'null' title: Bullish Pct description: Bullish tweet percentage for this date, calculated from positive sentiment-classified tweets examples: - 60 bearish_pct: anyOf: - type: integer maximum: 100.0 minimum: 0.0 - type: 'null' title: Bearish Pct description: Bearish tweet percentage for this date, calculated from negative sentiment-classified tweets examples: - 25 type: object required: - date - mentions title: XDailyTrendItem description: Daily trend data point for X/Twitter. InvalidSearchParametersError: properties: detail: anyOf: - $ref: '#/components/schemas/InvalidSearchParametersErrorDetail' - type: string title: Detail description: Structured search-parameter error or normalized-query validation message type: object required: - detail title: InvalidSearchParametersError description: Error response for invalid search query parameters. XTopTweet: properties: text_snippet: type: string maxLength: 280 title: Text Snippet description: Clean tweet paragraph around the detected ticker mention (truncated to 280 chars for this view) examples: - $TSLA breaking out! This is the move we've been waiting for 🚀 sentiment_score: anyOf: - type: number maximum: 1.0 minimum: -1.0 - type: 'null' title: Sentiment Score description: Sentiment score (-1 to +1) examples: - 0.85 sentiment_label: anyOf: - type: string - type: 'null' title: Sentiment Label description: Sentiment label (positive/negative/neutral) examples: - positive likes: type: integer minimum: 0.0 title: Likes description: Number of likes examples: - 1247 retweets: type: integer minimum: 0.0 title: Retweets description: Number of retweets examples: - 89 views: anyOf: - type: integer minimum: 0.0 - type: 'null' title: Views description: Number of views examples: - 52340 author: anyOf: - type: string - type: 'null' title: Author description: Author username examples: - elonmusk created_at: anyOf: - type: string - type: 'null' title: Created At description: Tweet creation time (ISO 8601) examples: - '2025-12-28T14:32:00Z' type: object required: - text_snippet - likes - retweets title: XTopTweet description: Top tweet mention for a stock - highest engagement tweets. examples: - text_snippet: $TSLA breaking out! This is the move we've been waiting for 🚀 sentiment_score: 0.85 sentiment_label: positive likes: 1247 retweets: 89 views: 52340 author: elonmusk created_at: '2025-12-28T14:32:00Z' UnsupportedAssetErrorDetail: properties: error_code: type: string title: Error Code description: Machine-readable unsupported asset error code examples: - unsupported_ticker message: type: string title: Message description: Human-readable unsupported asset message type: object required: - error_code - message title: UnsupportedAssetErrorDetail description: Structured detail for unsupported v1 stock/crypto asset requests. ErrorResponse: properties: detail: type: string title: Detail description: Human-readable error message examples: - Invalid API key. type: object required: - detail title: ErrorResponse description: Standard error response. examples: - detail: Missing API key. Include 'X-API-Key' header. - detail: Invalid API key. - detail: API key has been revoked. - detail: 'Rate limit exceeded: 100 per 1 minute' ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Loc description: Location of the invalid input msg: type: string title: Msg description: Validation failure message type: type: string title: Type description: Validation error type type: object required: - loc - msg - type title: ValidationError description: FastAPI/Pydantic validation error item. examples: - loc: - query - days msg: Input should be greater than or equal to 1 type: greater_than_equal XCompareStockItem: properties: ticker: type: string title: Ticker description: Stock ticker symbol examples: - TSLA company_name: anyOf: - type: string - type: 'null' title: Company Name description: Company name from ticker_reference examples: - Tesla, Inc. buzz_score: anyOf: - type: number maximum: 100.0 minimum: 0.0 - type: 'null' title: Buzz Score description: Aggregated Buzz Score (0-100) from X mentions examples: - 72.5 trend: anyOf: - type: string enum: - rising - falling - stable - type: 'null' title: Trend description: Activity momentum over the current 3 UTC days vs previous 3 UTC days, not price movement or Grok rank movement. Null when no qualifying X data exists. examples: - rising mentions: type: integer minimum: 0.0 title: Mentions description: Total tweet mentions examples: - 156 unique_tweets: type: integer minimum: 0.0 title: Unique Tweets description: Number of unique tweets mentioning this ticker (distinct tweet_id) examples: - 42 sentiment_score: anyOf: - type: number maximum: 1.0 minimum: -1.0 - type: 'null' title: Sentiment Score description: Average sentiment score from tweet analysis (-1 to +1) examples: - 0.35 bullish_pct: anyOf: - type: integer maximum: 100.0 minimum: 0.0 - type: 'null' title: Bullish Pct description: Percentage of bullish tweet mentions examples: - 45 bearish_pct: anyOf: - type: integer maximum: 100.0 minimum: 0.0 - type: 'null' title: Bearish Pct description: Percentage of bearish tweet mentions examples: - 12 total_upvotes: type: integer minimum: 0.0 title: Total Upvotes description: Total likes across all tweet mentions examples: - 2847 trend_history: items: type: number type: array title: Trend History description: Daily buzz history (oldest to newest). Length follows the resolved period, with a minimum of 7 values when data exists. Closed historical windows end at `to`. Empty when no qualifying data exists. examples: - - 45.2 - 48.1 - 52.3 - 55.0 - 58.2 - 61.5 - 72.5 type: object required: - ticker - buzz_score - mentions - unique_tweets - total_upvotes title: XCompareStockItem description: Individual stock in X/Twitter comparison. securitySchemes: ApiKeyAuth: type: apiKey description: 'API key for authentication. Get your API key at https://adanos.org/register. Format: `sk_live_` followed by 32 hexadecimal characters. Example: `REDACTED_STRIPE_KEY`.' in: header name: X-API-Key