{"openapi":"3.1.0","info":{"title":"Adanos Market Sentiment API","description":"\nMarket sentiment and attention data for **stocks** across **Reddit**, **X/Twitter**, **financial news**, **Polymarket**, plus **Reddit crypto** coverage and direct finance-tuned **text sentiment analysis**.\n\nThe core concepts across the API are **Buzz Score**, **Trend Detection** and directional **Sentiment**: they show what is moving, in which direction and on which platform.\n\nFor AI agents, the machine-readable reference is available at [`/llms.txt`](/llms.txt).\n\n## Quick Start\n\n### 1. Get an API key\n\nGet your API key from the website: [adanos.org/register](https://adanos.org/register)\n\n### 2. Make your first successful request\n\n```bash\ncurl \"https://api.adanos.org/reddit/stocks/v1/trending?limit=3\" \\\n  -H \"X-API-Key: sk_live_your_key_here\"\n```\n\n## How To Read Responses\n\n| Field | Meaning |\n|------|---------|\n| `buzz_score` | Normalized 0-100 popularity/attention score for that platform. Higher means more active and more relevant right now. |\n| `trend` | `rising`, `falling` or `stable` based on activity momentum over the current 3 UTC days vs previous 3 UTC days. It uses platform activity inputs such as mentions, engagement, breadth or market flow; for `from`/`to`, it anchors at `to` (or now when `to` is today). It is not price movement unless an endpoint explicitly says so. |\n| `sentiment_score` | Usually `-1.0` bearish to `+1.0` bullish. `null` means the platform had too little directional signal. |\n| `bullish_pct` / `bearish_pct` | Share of directional mentions or markets that were bullish vs bearish on that platform. |\n| `trend_history` | Independent UTC-day buzz scores, ordered oldest to newest. It is not directional trend history. The live final value describes today so far and can differ from the selected-period `buzz_score`. |\n| `period_days` | Lookback window used for that specific response. |\n| `found` | Legacy v1 detail-field planned for removal in v2. `true` means service data exists for this asset/window; `false` means the asset is supported, but the selected platform/window had no qualifying data. Unsupported assets return `404` with `detail.error_code`. |\n| `daily_trend[].buzz_score` | May be `null` when a per-day aggregate has not materialized yet; use the daily activity fields for charts and the parent `buzz_score` for the selected-window score. |\n| Search summaries | Present for every result. Zero values mean no qualifying platform signal in the selected period; nullable metadata/sentiment fields mean unknown or source-dependent data. |\n| `Null values` | Usually mean `null`: known field, but no signal/data for this asset in this period, not a schema mismatch. |\n\n## Platform Metric Parity\n\n| Platform | Primary activity field | Coverage / participation field | Engagement / market strength field |\n|----------|------------------------|--------------------------------|------------------------------------|\n| Reddit Stocks | `mentions` | `subreddit_count`, `unique_posts` | `total_upvotes` |\n| Reddit Crypto | `mentions` | `subreddit_count`, `unique_posts` | `total_upvotes` |\n| X/Twitter Stocks | `mentions` | `unique_tweets` | `total_upvotes` (likes) |\n| News Stocks | `mentions` | `source_count` | no social engagement field |\n| Polymarket Stocks | `trade_count` | `market_count` (market coverage), `unique_traders` (participants) | `total_liquidity` |\n\n## Authentication, Limits and Headers\n\n- Protected endpoints require `X-API-Key`.\n- Health-check endpoints are public.\n- Monthly quotas reset per account: free keys use their creation timestamp monthly anchor, paid keys use Stripe `current_period_end` when available.\n- Burst rate limits currently range from `100/min` on Free to `1,000/min` on paid plans.\n- Successful protected GET responses include:\n  - `X-RateLimit-Limit-Monthly`\n  - `X-RateLimit-Remaining-Monthly`\n  - `X-RateLimit-Used-Monthly`\n  - `X-RateLimit-Reset-Monthly`\n  - `X-RateLimit-Limit-Burst`\n  - `X-RateLimit-Remaining-Burst`\n  - `X-RateLimit-Reset-Burst`\n  - `X-Account-Type`\n- Successful GET responses include `Cache-Control`.\n\n## Official SDKs\n\n| SDK / Tool | Install | Link |\n|------------|---------|------|\n| Python SDK | `pip install adanos` | [PyPI](https://pypi.org/project/adanos/) |\n| TypeScript SDK | `npm install finance-sentiment` | [npm](https://www.npmjs.com/package/finance-sentiment) |\n| PHP SDK | `composer require adanos/adanos-php` | [Packagist](https://packagist.org/packages/adanos/adanos-php) |\n| CLI | `pip install adanos-cli` | [PyPI](https://pypi.org/project/adanos-cli/) |\n\n","contact":{"name":"API Support","url":"https://api.adanos.org/","email":"support@adanos.org"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"version":"1.49.0"},"servers":[{"url":"https://api.adanos.org","description":"Production"},{"url":"http://localhost:8000","description":"Development"}],"paths":{"/reddit/stocks/v1/trending":{"get":{"tags":["Reddit Stocks"],"summary":"Trending stocks","description":"Returns the Reddit stocks with the strongest discussion activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `unique_posts`, `subreddit_count`, `total_upvotes`: attributed volume and engagement signals, including inherited thread-context mentions\n- `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":"getTrendingStocks","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"},{"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/TrendingStock"},"title":"Response Gettrendingstocks"},"example":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"unique_posts":45,"subreddit_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"total_upvotes":15234,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.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 Gettrendingstocks"}}}},"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":"No trending stocks found","content":{"application/json":{"example":{"detail":"No trending stocks found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/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/reddit/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/reddit/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())"}]}},"/reddit/stocks/v1/trending/sectors":{"get":{"tags":["Reddit Stocks"],"summary":"Trending sectors","description":"Returns the sectors with the strongest aggregated Reddit stock discussion in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `mentions`, `unique_tickers`, `subreddit_count`, `total_upvotes`: attributed volume and engagement signals, including inherited thread-context mentions\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `top_tickers`: up to 5 tickers driving the sector result\n- `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":"getTrendingSectors","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/TrendingSector"},"title":"Response Gettrendingsectors"},"example":[{"buzz_score":78.4,"trend":"rising","mentions":4523,"unique_tickers":34,"subreddit_count":15,"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 Gettrendingsectors"}}}},"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":"No trending sectors found","content":{"application/json":{"example":{"detail":"No trending sectors found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/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/reddit/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/reddit/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())"}]}},"/reddit/stocks/v1/trending/countries":{"get":{"tags":["Reddit Stocks"],"summary":"Trending countries","description":"Returns the countries with the strongest aggregated Reddit stock discussion in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `mentions`, `unique_tickers`, `subreddit_count`, `total_upvotes`: attributed volume and engagement signals, including inherited thread-context mentions\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `top_tickers`: up to 5 tickers driving the country result\n- `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":"getTrendingCountries","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/TrendingCountry"},"title":"Response Gettrendingcountries"},"example":[{"buzz_score":82.3,"trend":"stable","mentions":8934,"unique_tickers":156,"subreddit_count":18,"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 Gettrendingcountries"}}}},"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":"No trending countries found","content":{"application/json":{"example":{"detail":"No trending countries found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/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/reddit/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/reddit/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())"}]}},"/reddit/stocks/v1/stock/{ticker}":{"get":{"tags":["Reddit Stocks"],"summary":"Stock Sentiment","description":"Returns detailed sentiment analysis for a specific stock ticker.\n\n**Includes:**\n- Buzz score (0-100)\n- Trend direction over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\n- Sentiment breakdown (positive/negative/neutral)\n- Daily trend data\n- `top_mentions`: top explicit Reddit mentions from the selected period, ranked by upvotes\n- `top_subreddits`: top subreddit contributors by attributed mention count\n\n`mentions` includes inherited thread-context mentions. Use raw `/mentions` without\n`include_inherited` for explicit-only rows.\n\nReturns `200` with `found: false` when the ticker is supported but this service\nhas no qualifying data in the requested window. Returns `404` only when the\nticker is unsupported.","operationId":"getStockSentiment","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)"},{"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/StockSentiment"},"example":{"ticker":"TSLA","company_name":"Tesla, Inc.","found":true,"buzz_score":87.5,"mentions":342,"sentiment_score":0.23,"total_upvotes":15234,"unique_posts":45,"subreddit_count":8,"trend":"rising","bullish_pct":45,"bearish_pct":18,"period_days":7,"top_subreddits":[{"subreddit":"wallstreetbets","mentions":89,"count":89},{"subreddit":"stocks","mentions":67,"count":67}],"daily_trend":[{"date":"2025-12-28","mentions":52,"sentiment_score":0.31,"buzz_score":42.8,"bullish_pct":58,"bearish_pct":19},{"date":"2025-12-27","mentions":48,"sentiment_score":0.18,"buzz_score":38.5,"bullish_pct":46,"bearish_pct":21}],"top_mentions":[{"text_snippet":"TSLA looking strong after...","sentiment_score":0.85,"sentiment_label":"positive","upvotes":1234,"subreddit":"wallstreetbets","created_utc":"2025-12-28T10:30:00"}]}}},"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 Getstocksentiment"}}}},"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/reddit/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/reddit/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/reddit/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())"}]}},"/reddit/stocks/v1/market-sentiment":{"get":{"tags":["Reddit Stocks"],"summary":"Market Sentiment","description":"Returns the service-level Reddit market sentiment snapshot across all tracked stocks when you want a single Reddit-wide market state instead of per-ticker rankings.\nIt includes service-wide buzz, sentiment split, activity trend, breadth metrics and the top drivers by current `buzz_score`.\n\n`buzz_score` here means relative Reddit market heat, not pure bullishness.\nIt measures how hot overall Reddit stock activity is versus Reddit's own trailing 90-day baseline:\n- around `50` = normal Reddit market activity\n- higher = more active than usual\n- lower = quieter than usual\n\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\n\nUse `sentiment_score`, `bullish_pct` and `bearish_pct` for direction.\n\n`mentions` includes inherited thread-context mentions. Use raw `/mentions` without\n`include_inherited` for explicit-only rows.","operationId":"getRedditMarketSentiment","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/RedditMarketSentimentResponse"},"example":{"buzz_score":57.4,"trend":"stable","mentions":3992,"unique_posts":418,"subreddit_count":21,"total_upvotes":15234,"active_tickers":1000,"sentiment_score":0.045,"positive_count":1440,"negative_count":998,"neutral_count":1554,"bullish_pct":36,"bearish_pct":25,"trend_history":[49.8,52.1,50.7,55.6,58.3,60.2,57.4],"drivers":[{"ticker":"SPY","mentions":129,"buzz_score":74.1,"sentiment_score":0.009},{"ticker":"GOOGL","mentions":106,"buzz_score":71.8,"sentiment_score":0.029}]}}},"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 Getredditmarketsentiment"}}}},"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/reddit/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/reddit/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/reddit/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())"}]}},"/reddit/stocks/v1/stock/{ticker}/explain":{"get":{"tags":["Reddit Stocks"],"summary":"AI explanation","description":"Returns an AI-generated explanation for why a stock is trending on Reddit, based on recent mention data and sentiment. Explanations are cached for 6 hours.\n\n**Includes:**\n- `explanation`: 1-2 sentence summary of why the stock is trending\n- `cached`: whether this was served from cache\n- `generated_at`: when the explanation was generated\n- `model`: which LLM model generated the explanation","operationId":"getStockExplanation","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 Getstockexplanation"}}}},"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/reddit/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/reddit/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/reddit/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())"}]}},"/reddit/stocks/v1/compare":{"get":{"tags":["Reddit Stocks"],"summary":"Compare stocks","description":"Compare up to 10 stock or ETF tickers side by side over the same UTC calendar-day period.\n\nResults are sorted by `buzz_score` descending and return the same core analytics used by\n`/trending`: `buzz_score`, `trend`, `trend_history`, `mentions`, `unique_posts`,\n`subreddit_count`, `sentiment_score`, `bullish_pct`, `bearish_pct` and `total_upvotes`.\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\n\nIf a requested ticker is supported but has no qualifying data in the period, it is still returned with zeroed metrics.\n\n`mentions` includes inherited thread-context mentions. Use raw `/mentions` without\n`include_inherited` for explicit-only rows.","operationId":"compareStocks","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/CompareResponse"},"example":{"period_days":7,"stocks":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"unique_posts":45,"subreddit_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"total_upvotes":15234,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]},{"ticker":"NVDA","company_name":"NVIDIA Corporation","buzz_score":72.3,"trend":"stable","mentions":189,"unique_posts":31,"subreddit_count":6,"sentiment_score":0.45,"bullish_pct":52,"bearish_pct":17,"total_upvotes":8921,"trend_history":[38.1,40.7,44.9,51.5,57.4,63.0,72.3]}]}}},"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 Comparestocks"}}}},"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/reddit/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/reddit/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/reddit/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())"}]}},"/reddit/stocks/v1/search":{"get":{"tags":["Reddit Stocks"],"summary":"Search stocks","description":"Search stocks by ticker, company name or alias. Results prioritize match relevance first (exact ticker matches, then prefixes, then name/alias matches) and include a compact summary block for the last 7 UTC calendar days. Summary mentions include inherited thread-context mentions; use raw /mentions without include_inherited for explicit-only rows.","operationId":"searchStocks","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/SearchResponse"},"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":342,"buzz_score":87.5,"trend":"rising","sentiment_score":0.23,"bearish_pct":18,"bullish_pct":45,"subreddit_count":8,"total_upvotes":15234,"unique_posts":45}}]}}},"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 Searchstocks"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/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/reddit/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/reddit/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())"}]}},"/reddit/stocks/v1/stats":{"get":{"tags":["Reddit Stocks"],"summary":"Service statistics","description":"Returns high-level Reddit stock dataset coverage metrics for questions like:\n- how many stock mention rows are stored\n- how many distinct tickers currently have Reddit data\n- how many mention rows and distinct tickers are present today (UTC)\n- how many supported tickers exist in the reference universe\n\nThe current-day counters count all rows in `reddit_mentions` since UTC midnight,\nincluding post mentions, comment mentions and inherited thread-context mentions.","operationId":"getStats","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedditStatsResponse"},"example":{"total_mentions":12833,"unique_tickers":65,"mentions_today":342,"unique_tickers_today":21,"supported_tickers":11800}}},"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/reddit/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/reddit/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/reddit/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())"}]}},"/reddit/stocks/v1/stock/{ticker}/mentions":{"get":{"tags":["Reddit Stocks"],"summary":"Raw Mentions","description":"Returns raw mention rows for a specific stock ticker within the live raw-data retention window.\n**Professional account required.** Free and Hobby accounts cannot use this endpoint.\n\n**Use this endpoint when you need:**\n- post/comment-level snippets\n- original timestamps\n- inherited-context filtering\n\n**Notes:**\n- Use `from` and `to` for explicit UTC date windows\n- Results are ordered newest first and support deterministic `offset` + `limit` pagination\n- `include_inherited=false` by default\n- empty result sets return `200` with `results=[]`","operationId":"getStockRawMentions","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)"},{"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 mention rows to return","examples":[50],"default":50,"title":"Limit"},"description":"Maximum number of raw mention 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."},{"name":"include_inherited","in":"query","required":false,"schema":{"type":"boolean","description":"Include thread-context inherited mentions in addition to direct ticker mentions","default":false,"title":"Include Inherited"},"description":"Include thread-context inherited mentions in addition to direct ticker mentions"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedditRawMentionsResponse"},"example":{"ticker":"TSLA","period_days":7,"count":1,"results":[{"post_id":"abc123","comment_id":"def456","subreddit":"wallstreetbets","author":"user123","text_snippet":"TSLA looks strong into earnings...","created_utc":"2026-03-20T18:42:10Z","upvotes":381,"sentiment_score":0.62,"sentiment_label":"positive","is_inherited":false}]}}},"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 Getstockrawmentions"}}}},"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/reddit/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/reddit/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/reddit/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())"}]}},"/reddit/crypto/v1/trending":{"get":{"tags":["Reddit Crypto"],"summary":"Trending tokens","description":"Returns the crypto assets with the strongest Reddit discussion activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `unique_posts`, `subreddit_count`, `total_upvotes`: attributed volume and engagement signals, including inherited thread-context mentions\n- `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":"getRedditCryptoTrending","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 tokens to return","default":20,"title":"Limit"},"description":"Maximum tokens to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"Offset"},"description":"Pagination offset"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CryptoTrendingToken"},"title":"Response Getredditcryptotrending"},"example":[{"symbol":"BTC","name":"Bitcoin","buzz_score":78.1,"trend":"rising","mentions":423,"unique_posts":97,"subreddit_count":12,"sentiment_score":0.31,"bullish_pct":47,"bearish_pct":18,"total_upvotes":15620,"trend_history":[42.3,46.8,51.2,58.9,64.0,71.4,78.1]}]}},"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 Getredditcryptotrending"}}}},"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":"No trending crypto tokens found","content":{"application/json":{"example":{"detail":"No trending crypto tokens found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/crypto/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/reddit/crypto/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/reddit/crypto/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())"}]}},"/reddit/crypto/v1/token/{symbol}":{"get":{"tags":["Reddit Crypto"],"summary":"Token Sentiment","description":"Returns the detailed Reddit report for one crypto symbol.\n\n**Includes:**\n- `buzz_score`: normalized Reddit activity score for the selected period\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `unique_posts`, `subreddit_count`, `total_upvotes`: attributed volume and engagement signals, including inherited thread-context mentions\n- `daily_trend`: daily Reddit activity and sentiment values\n- `top_mentions`: representative high-engagement Reddit posts or comments from the selected period\n\nReturns `200` with `found: false` when the symbol is supported but this service\nhas no qualifying data in the requested window. Returns `404` only when the\nsymbol is unsupported.","operationId":"getRedditCryptoToken","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","pattern":"^\\$?[A-Za-z0-9]{1,20}$","description":"Crypto symbol (e.g., BTC, $ETH, SOL)","title":"Symbol"},"description":"Crypto symbol (e.g., BTC, $ETH, SOL)"},{"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/CryptoTokenSentiment"},"example":{"symbol":"ETH","name":"Ethereum","found":true,"buzz_score":72.4,"mentions":318,"sentiment_score":0.27,"total_upvotes":10422,"unique_posts":73,"subreddit_count":9,"trend":"stable","bullish_pct":43,"bearish_pct":19,"period_days":7,"top_subreddits":[{"subreddit":"ethtrader","mentions":91,"count":91},{"subreddit":"cryptocurrency","mentions":84,"count":84}],"daily_trend":[{"date":"2026-02-24","mentions":48,"sentiment_score":0.22,"buzz_score":56.4,"bullish_pct":58,"bearish_pct":21},{"date":"2026-02-23","mentions":42,"sentiment_score":0.19,"buzz_score":51.7,"bullish_pct":52,"bearish_pct":24}],"top_mentions":[{"text_snippet":"ETH setup still looks strong into the next catalyst.","sentiment_score":0.74,"sentiment_label":"positive","upvotes":1200,"subreddit":"ethtrader","created_utc":"2026-02-24T09:15:00Z"}]}}},"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 Getredditcryptotoken"}}}},"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 crypto symbol","content":{"application/json":{"example":{"detail":{"error_code":"unsupported_symbol","message":"Unsupported symbol ZZZ. This symbol is not supported by Adanos v1."}},"schema":{"$ref":"#/components/schemas/UnsupportedAssetError"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/crypto/v1/token/BTC?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/reddit/crypto/v1/token/BTC?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/reddit/crypto/v1/token/BTC?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())"}]}},"/reddit/crypto/v1/market-sentiment":{"get":{"tags":["Reddit Crypto"],"summary":"Market Sentiment","description":"Returns the service-level Reddit Crypto market sentiment snapshot across all tracked assets when you want a single Reddit-Crypto-wide market state instead of per-asset rankings.\nIt includes service-wide buzz, sentiment split, activity trend, breadth metrics and the top drivers by current `buzz_score`.\n\n`buzz_score` here means relative Reddit Crypto market heat, not pure bullishness.\nIt measures how hot overall Reddit crypto discussion is versus Reddit Crypto's own trailing 90-day baseline:\n- around `50` = normal Reddit crypto activity\n- higher = more active than usual\n- lower = quieter than usual\n\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\n\nUse `sentiment_score`, `bullish_pct` and `bearish_pct` for direction.\n\n`mentions` includes inherited thread-context mentions. Use raw `/mentions` without\n`include_inherited` for explicit-only rows.","operationId":"getRedditCryptoMarketSentiment","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/CryptoMarketSentimentResponse"},"example":{"buzz_score":52.4,"trend":"stable","mentions":5412,"unique_posts":1184,"subreddit_count":37,"total_upvotes":41290,"active_tickers":89,"sentiment_score":0.117,"positive_count":2101,"negative_count":1318,"neutral_count":1993,"bullish_pct":39,"bearish_pct":24,"trend_history":[47.1,49.3,50.4,52.2,51.8,53.0,52.4],"drivers":[{"symbol":"BTC","mentions":423,"buzz_score":78.1,"sentiment_score":0.31},{"symbol":"ETH","mentions":318,"buzz_score":72.4,"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 Getredditcryptomarketsentiment"}}}},"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/reddit/crypto/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/reddit/crypto/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/reddit/crypto/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())"}]}},"/reddit/crypto/v1/compare":{"get":{"tags":["Reddit Crypto"],"summary":"Compare tokens","description":"Compare up to 10 crypto symbols side by side over the same UTC calendar-day period.\n\nUse it when you already know the symbols and want a compact ranked table instead of full detail reports.\nResults are sorted by `buzz_score` descending and include attributed `mentions`, `trend`, `trend_history`, `unique_posts`, `subreddit_count`, `sentiment_score`, `bullish_pct`, `bearish_pct` and `total_upvotes`.\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","operationId":"compareRedditCryptoTokens","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":"symbols","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated symbols (e.g., BTC,ETH,SOL)","title":"Symbols"},"description":"Comma-separated symbols (e.g., BTC,ETH,SOL)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoCompareResponse"},"example":{"period_days":7,"tokens":[{"symbol":"BTC","name":"Bitcoin","buzz_score":78.1,"trend":"rising","mentions":423,"unique_posts":97,"subreddit_count":12,"sentiment_score":0.31,"bullish_pct":47,"bearish_pct":18,"total_upvotes":15620,"trend_history":[42.3,46.8,51.2,58.9,64.0,71.4,78.1]},{"symbol":"ETH","name":"Ethereum","buzz_score":72.4,"trend":"stable","mentions":318,"unique_posts":73,"subreddit_count":9,"sentiment_score":0.27,"bullish_pct":43,"bearish_pct":19,"total_upvotes":10422,"trend_history":[36.2,41.4,46.7,53.1,60.2,66.5,72.4]}]}}},"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 Compareredditcryptotokens"}}}},"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_symbols","message":"Maximum 10 symbols allowed.","max_items":10,"item_name":"symbol"}},"examples":{"too_many_symbols":{"summary":"Too many symbols","value":{"detail":{"error":"too_many_symbols","message":"Maximum 10 symbols allowed.","max_items":10,"item_name":"symbol"}}},"no_valid_symbols":{"summary":"No valid symbols","value":{"detail":{"error":"no_valid_symbols","message":"At least one valid symbol is required.","max_items":10,"item_name":"symbol"}}}},"schema":{"$ref":"#/components/schemas/CompareLimitError"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/crypto/v1/compare?from=2026-05-01&to=2026-05-07&symbols=BTC,ETH,SOL\" \\\n  -H \"X-API-Key: sk_live_your_key_here\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/crypto/v1/compare?from=2026-05-01&to=2026-05-07&symbols=BTC,ETH,SOL\", {\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/reddit/crypto/v1/compare?from=2026-05-01&to=2026-05-07&symbols=BTC,ETH,SOL\",\n    headers={\n        \"X-API-Key\": \"sk_live_your_key_here\",\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/crypto/v1/search":{"get":{"tags":["Reddit Crypto"],"summary":"Search tokens","description":"Search known crypto assets by symbol, name or alias. Results prioritize exact symbol matches first, then prefixes, then name/alias matches and include a compact `summary` block for the last 7 UTC calendar days.\nSummary `mentions` includes inherited thread-context mentions.","operationId":"searchRedditCrypto","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"description":"Search query (minimum 2 non-$ characters after trimming)","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/CryptoSearchResponse"},"example":{"query":"solana","count":1,"period_days":7,"results":[{"symbol":"SOL","name":"Solana","market_cap_rank":6,"market_cap_usd":71234567890.12,"aliases":["Sol"],"summary":{"mentions":287,"buzz_score":72.4,"trend":"stable","sentiment_score":0.27,"bearish_pct":19,"bullish_pct":43,"subreddit_count":9,"total_upvotes":10422,"unique_posts":73}}]}}},"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 Searchredditcrypto"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/crypto/v1/search?q=bitcoin&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/reddit/crypto/v1/search?q=bitcoin&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/reddit/crypto/v1/search?q=bitcoin&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())"}]}},"/reddit/crypto/v1/stats":{"get":{"tags":["Reddit Crypto"],"summary":"Service statistics","description":"Returns high-level Reddit Crypto dataset coverage metrics.\n\nIncludes:\n- total mention rows stored\n- number of distinct tracked symbols with data, exposed as `unique_tokens`\n- today's UTC mention and distinct symbol counts, exposed as `unique_tokens_today`\n- total supported symbols available to the search/detector layer, exposed as `supported_tokens`","operationId":"getRedditCryptoStats","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoStatsResponse"},"example":{"total_mentions":18352,"unique_tokens":142,"mentions_today":287,"unique_tokens_today":35,"supported_tokens":500}}},"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/reddit/crypto/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/reddit/crypto/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/reddit/crypto/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())"}]}},"/reddit/crypto/v1/token/{symbol}/mentions":{"get":{"tags":["Reddit Crypto"],"summary":"Raw Mentions","description":"Returns raw Reddit mention rows for a specific crypto symbol within the live raw-data retention window.\n**Professional account required.** Free and Hobby accounts cannot use this endpoint.\n\n**Use this endpoint when you need:**\n- post/comment-level snippets\n- original timestamps\n- inherited-context filtering\n\n**Notes:**\n- Use `from` and `to` for explicit UTC date windows\n- Results are ordered newest first and support deterministic `offset` + `limit` pagination\n- `include_inherited=false` by default\n- empty result sets return `200` with `results=[]`","operationId":"getRedditCryptoTokenMentions","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","pattern":"^\\$?[A-Za-z0-9]{1,20}$","description":"Crypto symbol (e.g., BTC, $ETH, SOL)","title":"Symbol"},"description":"Crypto symbol (e.g., BTC, $ETH, SOL)"},{"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 mentions to return","default":50,"title":"Limit"},"description":"Maximum number of raw mentions 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.","default":0,"title":"Offset"},"description":"Number of raw mention rows to skip for offset-based pagination."},{"name":"include_inherited","in":"query","required":false,"schema":{"type":"boolean","description":"Include inherited thread-context mentions in addition to direct symbol matches","default":false,"title":"Include Inherited"},"description":"Include inherited thread-context mentions in addition to direct symbol matches"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoRawMentionsResponse"},"example":{"symbol":"BTC","period_days":7,"count":1,"results":[{"post_id":"abc123","comment_id":"def456","subreddit":"cryptocurrency","author":"user123","text_snippet":"BTC still looks strong above this range...","created_utc":"2026-03-20T18:42:10Z","upvotes":381,"sentiment_score":0.62,"sentiment_label":"positive","is_inherited":false}]}}},"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 Getredditcryptotokenmentions"}}}},"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/reddit/crypto/v1/token/BTC/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/reddit/crypto/v1/token/BTC/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/reddit/crypto/v1/token/BTC/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())"}]}},"/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`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `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)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `unique_tweets`, `total_upvotes`: volume and engagement signals\n- `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`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `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)\n- `mentions`, `unique_tickers`, `total_upvotes`: volume and engagement signals\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `top_tickers`: up to 5 tickers driving the sector result\n- `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`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `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)\n- `mentions`, `unique_tickers`, `total_upvotes`: volume and engagement signals\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `top_tickers`: up to 5 tickers driving the country result\n- `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.\n\n**Includes:**\n- `buzz_score`: normalized X/Twitter activity score for the selected period\n- `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)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `unique_tweets`, `total_upvotes`: volume and engagement signals\n- `daily_trend`: daily X/Twitter activity and sentiment values\n- `top_tweets`: representative high-engagement tweets from the selected period\n\nReturns `200` with `found: false` when the ticker is supported but this service\nhas no qualifying data in the requested window. Returns `404` only when the\nticker 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.\nIt includes service-wide buzz, sentiment split, activity trend, breadth metrics and the top drivers by current `buzz_score`.\n\n`buzz_score` here means relative X/Twitter market heat, not pure bullishness.\nIt measures how hot overall X stock discussion is versus X's own trailing 90-day baseline:\n- around `50` = normal X market activity\n- higher = more active than usual\n- lower = quieter than usual\n\n`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).\n\nUse `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.\n\n**Includes:**\n- `explanation`: 1-2 sentence summary of why the stock is trending\n- `cached`: whether this was served from cache\n- `generated_at`: when the explanation was generated\n- `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.\n\nUse it when you already know the tickers and want a compact ranked table instead of full detail reports.\nResults are sorted by `buzz_score` descending and include `trend`, `trend_history`, `mentions`, `unique_tweets`, `sentiment_score`, `bullish_pct`, `bearish_pct` and `total_upvotes`.\n`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.\n\nIncludes:\n- total X mentions in the database\n- number of unique tickers with X mentions\n- today's UTC X mention and distinct ticker counts\n- 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":11800}}},"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.\n**Professional account required.** Free and Hobby accounts cannot use this endpoint.\n\n**Use this endpoint when you need:**\n- tweet-level snippets\n- original timestamps\n- engagement counters on the raw rows\n\n**Notes:**\n- Use `from` and `to` for explicit UTC date windows\n- Results are ordered newest first and support deterministic `offset` + `limit` pagination\n- 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())"}]}},"/polymarket/stocks/v1/trending":{"get":{"tags":["Polymarket Stocks"],"summary":"Trending stocks","description":"Returns the stocks with the strongest Polymarket prediction-market activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking; bullish and bearish market activity can both rank highly\n- `trend`: flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: outcome-aware market sentiment signals\n- `trade_count`, `market_count`, `unique_traders`, `total_liquidity`: activity, breadth, observed participation and liquidity signals\n- `trend_history`: independent UTC-day buzz scores, oldest to newest; minimum 7 values. For a closed single-day window with an available final Daily score, the final value equals `buzz_score`; live and multi-day values can differ. Missing days are `0.0`","operationId":"getPolymarketTrendingStocks","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","examples":[0],"default":0,"title":"Offset"},"description":"Number of items to skip"},{"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/PolymarketTrendingStock"},"title":"Response Getpolymarkettrendingstocks"},"example":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":71.4,"trend":"rising","trade_count":312,"market_count":27,"current_market_count":12,"unique_traders":119,"sentiment_score":0.34,"bullish_pct":67,"bearish_pct":33,"total_liquidity":94750.0,"trend_history":[48.2,51.0,55.3,61.1,65.8,69.2,71.4]}]}},"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 Getpolymarkettrendingstocks"}}}},"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/polymarket/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/polymarket/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/polymarket/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())"}]}},"/polymarket/stocks/v1/trending/sectors":{"get":{"tags":["Polymarket Stocks"],"summary":"Trending sectors","description":"Returns the sectors with the strongest aggregated Polymarket prediction-market activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `trade_count`, `market_count`, `unique_traders`, `total_liquidity`: activity, breadth, observed participation and liquidity signals\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: outcome-aware market sentiment signals\n- `top_tickers`: up to 5 tickers driving the sector result","operationId":"getPolymarketTrendingSectors","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 sectors to return","examples":[20],"default":20,"title":"Limit"},"description":"Maximum sectors to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip","examples":[0],"default":0,"title":"Offset"},"description":"Number of items to skip"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PolymarketTrendingSector"},"title":"Response Getpolymarkettrendingsectors"},"example":[{"buzz_score":72.8,"trend":"rising","trade_count":312,"market_count":147,"current_market_count":71,"unique_tickers":6,"unique_traders":211,"sentiment_score":0.22,"bullish_pct":61,"bearish_pct":39,"total_liquidity":325000.0,"trend_history":[48.2,51.0,55.3,61.1,65.8,69.2,72.8],"top_tickers":["AAPL","MSFT","NVDA","TSLA","AMD"],"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 Getpolymarkettrendingsectors"}}}},"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/polymarket/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/polymarket/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/polymarket/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())"}]}},"/polymarket/stocks/v1/trending/countries":{"get":{"tags":["Polymarket Stocks"],"summary":"Trending countries","description":"Returns the countries with the strongest aggregated Polymarket prediction-market activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `trade_count`, `market_count`, `unique_traders`, `total_liquidity`: activity, breadth, observed participation and liquidity signals\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: outcome-aware market sentiment signals\n- `top_tickers`: up to 5 tickers driving the country result","operationId":"getPolymarketTrendingCountries","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 countries to return","examples":[20],"default":20,"title":"Limit"},"description":"Maximum countries to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip","examples":[0],"default":0,"title":"Offset"},"description":"Number of items to skip"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PolymarketTrendingCountry"},"title":"Response Getpolymarkettrendingcountries"},"example":[{"buzz_score":70.1,"trend":"stable","trade_count":712,"market_count":265,"current_market_count":129,"unique_tickers":10,"unique_traders":402,"sentiment_score":0.18,"bullish_pct":58,"bearish_pct":42,"total_liquidity":472000.0,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,70.1],"top_tickers":["AAPL","TSLA","NVDA","AMZN","GOOGL"],"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 Getpolymarkettrendingcountries"}}}},"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/polymarket/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/polymarket/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/polymarket/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())"}]}},"/polymarket/stocks/v1/stock/{ticker}":{"get":{"tags":["Polymarket Stocks"],"summary":"Stock Sentiment","description":"Returns Polymarket-based sentiment and activity for one stock ticker.\n\nThe response combines:\n- Period metrics for the date window defined by `days` or `from`/`to`.\n- Representative market-level evidence in `top_mentions`.\n- A compact current market read in `pulse`.\n\n**Fields:**\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: outcome-aware sentiment derived from Polymarket market prices and outcomes\n- `buzz_score`: normalized activity score for the selected period; both bullish and bearish activity can increase buzz\n- `trend`: recent flow momentum, comparing the current 3 UTC days with the previous 3 UTC days using trades, volume, market breadth and liquidity; this is not stock price movement\n- `trade_count`, `market_count`, `unique_traders`, `total_liquidity`: period activity, breadth, observed participation and liquidity\n- `daily_trend`: daily activity and sentiment values for the selected window\n- `top_mentions`: representative Polymarket markets behind the ticker-level signals, including market-level `sentiment_score` and `buzz_score`\n- `pulse`: compact current interpretation from the latest stored open-market snapshots\n\n**Notes:**\n- `pulse` is current-state oriented and does not duplicate aggregate response fields.\n- Use `top_mentions` for concrete market examples; `pulse` intentionally stays compact.\n- `top_mentions` includes only markets observed active/open in the selected period; ranking prioritizes outcome-aware directional evidence, keeps opposing signals visible when present, then uses trade count, market status, volume and liquidity as tie-breakers.\n- Prices, volume and liquidity in `top_mentions` come from the selected in-period snapshot, not necessarily the latest live market state.\n- `active` indicates whether the market is currently open, so older in-period evidence can now be inactive, resolved or expired.\n- `market_status` can be `tradable`, `open`, `resolved`, `expired` or `inactive`.\n- For windows longer than snapshot retention, aggregate metrics can still use `polymarket_daily_stats`; `top_mentions` is limited to retained or stored representative market snapshots.\n- 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":"getPolymarketStock","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":["AAPL","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}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketStockDetailResponse"},"example":{"ticker":"AAPL","company_name":"Apple Inc.","found":true,"buzz_score":68.9,"trend":"stable","period_days":7,"trade_count":312,"market_count":27,"current_market_count":12,"unique_traders":119,"sentiment_score":0.28,"bullish_pct":64,"bearish_pct":36,"total_liquidity":128000.0,"daily_trend":[{"date":"2026-02-13","trade_count":5,"sentiment_score":0.25,"buzz_score":64.1,"bullish_pct":64,"bearish_pct":21}],"top_mentions":[{"condition_id":"0xabc...","question":"Will AAPL close above $220 this week?","market_type":"close_above","trade_count":42,"sentiment_score":0.23,"buzz_score":77.2,"yes_price":0.62,"no_price":0.38,"liquidity":7905.52,"volume_24h":2408.43,"end_date":"2026-02-28","active":true,"market_status":"tradable"}],"pulse":{"mood":"mixed","confidence":60.0,"thin_data":false,"why":["opposing_market_signals","upside_targets_rejected","floor_support"],"warnings":["high_average_spread","low_trade_breadth"],"evidence":{"directional_coverage":1.0,"traded_market_pct":0.231,"zero_trade_market_pct":0.769,"avg_spread":0.099,"snapshot_at":"2026-06-24T06:25:53Z"}}}}},"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 Getpolymarketstock"}}}},"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/polymarket/stocks/v1/stock/AAPL?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/polymarket/stocks/v1/stock/AAPL?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/polymarket/stocks/v1/stock/AAPL?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())"}]}},"/polymarket/stocks/v1/market-sentiment":{"get":{"tags":["Polymarket Stocks"],"summary":"Market Sentiment","description":"Returns the service-level Polymarket market sentiment snapshot across all tracked stocks when you want a single Polymarket-wide market state instead of per-ticker rankings.\nIt includes service-wide buzz, sentiment split, activity trend, breadth metrics and the top drivers by current `buzz_score`.\n\n`buzz_score` here means relative Polymarket market heat, not pure bullishness.\nIt measures how hot overall Polymarket stock-market activity is versus Polymarket's own trailing 90-day baseline:\n- around `50` = normal market activity\n- higher = more active than usual\n- lower = quieter than usual\n\n`trend` is flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\n\nUse `sentiment_score`, `bullish_pct` and `bearish_pct` for direction.","operationId":"getPolymarketMarketSentiment","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/PolymarketMarketSentimentResponse"},"example":{"buzz_score":58.4,"trend":"stable","trade_count":512,"market_count":93,"current_market_count":64,"unique_traders":281,"total_liquidity":245000.0,"active_tickers":31,"sentiment_score":0.11,"positive_count":41,"negative_count":29,"neutral_count":23,"bullish_pct":44,"bearish_pct":31,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,58.4],"drivers":[{"ticker":"AAPL","trade_count":52,"buzz_score":68.9,"sentiment_score":0.28},{"ticker":"TSLA","trade_count":47,"buzz_score":66.3,"sentiment_score":0.19}]}}},"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 Getpolymarketmarketsentiment"}}}},"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/polymarket/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/polymarket/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/polymarket/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())"}]}},"/polymarket/stocks/v1/compare":{"get":{"tags":["Polymarket Stocks"],"summary":"Compare stocks","description":"Compare up to 10 stock or ETF tickers side by side using Polymarket market activity.\n\nUse it when you already know the tickers and want a compact ranked table instead of full detail reports.\nResults are sorted by `buzz_score` descending and include `trend`, `trend_history`, `trade_count`, `market_count`, `current_market_count`, `unique_traders`, `sentiment_score`, `bullish_pct`, `bearish_pct` and `total_liquidity`.\n`trend` is flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","operationId":"comparePolymarketStocks","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 ticker list (max 10)","examples":["TSLA,NVDA,AMD"],"title":"Tickers"},"description":"Comma-separated ticker list (max 10)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketCompareResponse"},"example":{"period_days":7,"stocks":[{"ticker":"AAPL","company_name":"Apple Inc.","buzz_score":68.9,"trend":"stable","trade_count":312,"market_count":27,"current_market_count":12,"unique_traders":119,"sentiment_score":0.28,"bullish_pct":64,"bearish_pct":36,"total_liquidity":128000.0,"trend_history":[48.2,51.0,55.3,61.1,65.8,69.2,68.9]}]}}},"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 Comparepolymarketstocks"}}}},"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/polymarket/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/polymarket/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/polymarket/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())"}]}},"/polymarket/stocks/v1/search":{"get":{"tags":["Polymarket Stocks"],"summary":"Search stocks","description":"Search supported stocks and ETFs, then enrich the matches with Polymarket activity. 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":"searchPolymarketStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":50,"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/PolymarketSearchResponse"},"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":{"trade_count":14,"buzz_score":71.4,"trend":"rising","sentiment_score":0.34,"bearish_pct":33,"bullish_pct":67,"current_market_count":12,"market_count":27,"total_liquidity":94750.0,"unique_traders":119}}]}}},"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 Searchpolymarketstocks"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/polymarket/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/polymarket/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/polymarket/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())"}]}},"/polymarket/stocks/v1/stats":{"get":{"tags":["Polymarket Stocks"],"summary":"Service statistics","description":"Returns high-level database coverage metrics for the Polymarket stock dataset.\n\nUse this endpoint to understand how much market activity is indexed:\n- total aggregated trade activity\n- total distinct markets captured\n- unique stock tickers with indexed Polymarket market rows\n- currently open markets and tickers\n- today's UTC trade activity, traded markets and traded tickers\n- supported ticker count from the reference universe","operationId":"getPolymarketStats","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketStatsResponse"},"example":{"total_trades":15420,"total_markets":713,"unique_tickers":119,"open_markets_current":284,"open_tickers_current":71,"traded_markets_today":39,"traded_tickers_today":17,"trades_today":84,"supported_tickers":11800}}},"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/polymarket/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/polymarket/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/polymarket/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())"}]}},"/polymarket/stocks/v1/stock/{ticker}/mentions":{"get":{"tags":["Polymarket Stocks"],"summary":"Raw Mentions","description":"Returns raw Polymarket market snapshot rows for a specific ticker within the live raw-data retention window.\n**Professional account required.** Free and Hobby accounts cannot use this endpoint.\n\n**Use this endpoint when you need:**\n- original market questions, prices, liquidity, volume, trade counters and timestamps\n- outcome-aware market price sentiment for individual snapshot rows\n- repeated snapshots for the same market over time\n\n**Notes:**\n- Use `from` and `to` for explicit UTC date windows\n- Results are ordered newest first and support deterministic `offset` + `limit` pagination\n- empty result sets return `200` with `results=[]`\n- The same `condition_id` can appear multiple times across different `fetched_at` snapshots\n- `active` indicates whether the market is currently open, using the latest stored state for that `condition_id`; `market_status` compactly distinguishes `tradable`, `open`, `resolved`, `expired` and `inactive`\n- `buy_trades` and `sell_trades` are activity counters, not bullish/bearish sentiment","operationId":"getPolymarketStockRawMentions","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":90,"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 Polymarket snapshot rows to return","examples":[50],"default":50,"title":"Limit"},"description":"Maximum number of raw Polymarket snapshot 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/PolymarketRawMentionsResponse"},"example":{"ticker":"NVDA","period_days":7,"count":1,"results":[{"condition_id":"0xabc...","event_id":"12345","market_slug":"nvda-up-or-down-on-april-20-2026","question":"NVDA up or down on April 20?","market_type":"up_down","strike_price":250.0,"yes_price":0.63,"no_price":0.37,"reference_price":247.82,"reference_price_timestamp":"2026-04-20T14:30:00Z","liquidity":7905.52,"volume_24h":2408.43,"trade_count":42,"buy_trades":23,"sell_trades":19,"unique_traders":31,"sentiment_score":0.26,"sentiment_label":"positive","end_date":"2026-04-20T23:59:00Z","active":true,"market_status":"tradable","fetched_at":"2026-04-20T15:00:00Z"}]}}},"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 Getpolymarketstockrawmentions"}}}},"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/polymarket/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/polymarket/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/polymarket/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())"}]}},"/news/stocks/v1/trending":{"get":{"tags":["News Stocks"],"summary":"Trending stocks","description":"Returns the stocks with the strongest news coverage activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `source_count`: coverage volume and source breadth signals\n- `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`\n\nUse `source` only when you want the ranking filtered to one publisher or source family.","operationId":"getNewsTrendingStocks","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","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","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.","title":"Type"},"description":"Filter by asset type. Omit or use 'all' for all assets."},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional source filter (strict canonical source id or known alias)","title":"Source"},"description":"Optional source filter (strict canonical source id or known alias)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NewsTrendingStock"},"title":"Response Getnewstrendingstocks"},"example":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"source_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.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 Getnewstrendingstocks"}}}},"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":"No trending stocks found","content":{"application/json":{"example":{"detail":"No trending stocks found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/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/news/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/news/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())"}]}},"/news/stocks/v1/trending/sectors":{"get":{"tags":["News Stocks"],"summary":"Trending sectors","description":"Returns the sectors with the strongest aggregated news coverage activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `mentions`, `unique_tickers`, `source_count`: coverage volume and breadth signals\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `top_tickers`: up to 5 tickers driving the sector result\n\nUse `source` only when you want the ranking filtered to one publisher or source family.","operationId":"getNewsTrendingSectors","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","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","default":0,"title":"Offset"},"description":"Number of items to skip for pagination"},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional source filter (strict canonical source id or known alias)","title":"Source"},"description":"Optional source filter (strict canonical source id or known alias)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NewsTrendingSector"},"title":"Response Getnewstrendingsectors"},"example":[{"buzz_score":78.4,"trend":"rising","mentions":4523,"unique_tickers":34,"source_count":15,"sentiment_score":0.28,"bullish_pct":54,"bearish_pct":22,"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 Getnewstrendingsectors"}}}},"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":"No trending sectors found","content":{"application/json":{"example":{"detail":"No trending sectors found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/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/news/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/news/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())"}]}},"/news/stocks/v1/trending/countries":{"get":{"tags":["News Stocks"],"summary":"Trending countries","description":"Returns the countries with the strongest aggregated news coverage activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `mentions`, `unique_tickers`, `source_count`: coverage volume and breadth signals\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `top_tickers`: up to 5 tickers driving the country result\n\nUse `source` only when you want the ranking filtered to one publisher or source family.","operationId":"getNewsTrendingCountries","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","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","default":0,"title":"Offset"},"description":"Number of items to skip for pagination"},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional source filter (strict canonical source id or known alias)","title":"Source"},"description":"Optional source filter (strict canonical source id or known alias)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NewsTrendingCountry"},"title":"Response Getnewstrendingcountries"},"example":[{"buzz_score":82.3,"trend":"stable","mentions":8934,"unique_tickers":156,"source_count":18,"sentiment_score":0.21,"bullish_pct":48,"bearish_pct":26,"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 Getnewstrendingcountries"}}}},"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":"No trending countries found","content":{"application/json":{"example":{"detail":"No trending countries found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/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/news/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/news/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())"}]}},"/news/stocks/v1/stock/{ticker}":{"get":{"tags":["News Stocks"],"summary":"Stock Sentiment","description":"Return the detailed news sentiment report for one stock ticker.\n\n**Includes:**\n- `buzz_score`: normalized news activity score for the selected period\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `source_count`: coverage volume and source breadth signals\n- `daily_trend`: daily news activity and sentiment values\n- `top_mentions`: representative recent articles from the selected period, with source attribution\n- `top_sources`: top source contributors by mention count\n\nReturns `200` with `found: false` when the ticker is supported but this service\nhas no qualifying data in the requested window. Returns `404` only when the\nticker is unsupported.","operationId":"getNewsStockSentiment","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)"},{"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/NewsStockSentiment"},"example":{"ticker":"TSLA","company_name":"Tesla, Inc.","found":true,"buzz_score":87.5,"mentions":342,"sentiment_score":0.23,"source_count":8,"trend":"rising","bullish_pct":45,"bearish_pct":18,"period_days":7,"top_sources":[{"source":"reuters","mentions":89,"count":89},{"source":"benzinga","mentions":67,"count":67}],"daily_trend":[{"date":"2026-03-05","mentions":52,"sentiment_score":0.31,"buzz_score":42.8,"bullish_pct":58,"bearish_pct":19},{"date":"2026-03-04","mentions":48,"sentiment_score":0.18,"buzz_score":38.5,"bullish_pct":46,"bearish_pct":21}],"top_mentions":[{"text_snippet":"TSLA looking strong after production update...","sentiment_score":0.85,"sentiment_label":"positive","source":"reuters","created_utc":"2026-03-05T10:30:00+00:00"}]}}},"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 Getnewsstocksentiment"}}}},"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/news/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/news/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/news/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())"}]}},"/news/stocks/v1/market-sentiment":{"get":{"tags":["News Stocks"],"summary":"Market Sentiment","description":"Returns the service-level News market sentiment snapshot across all tracked stocks when you want a single News-wide market state instead of per-ticker rankings.\nIt includes service-wide buzz, sentiment split, activity trend, breadth metrics and the top drivers by current `buzz_score`.\n\n`buzz_score` here means relative News market heat, not pure bullishness.\nIt measures how hot overall stock news flow is versus News' own trailing 90-day baseline:\n- around `50` = normal news activity\n- higher = broader coverage than usual\n- lower = quieter than usual\n\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\n\nUse `sentiment_score`, `bullish_pct` and `bearish_pct` for direction.","operationId":"getNewsMarketSentiment","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/NewsMarketSentimentResponse"},"example":{"buzz_score":53.8,"trend":"stable","mentions":1298,"unique_articles":911,"source_count":44,"active_tickers":233,"sentiment_score":0.064,"positive_count":512,"negative_count":308,"neutral_count":478,"bullish_pct":39,"bearish_pct":24,"trend_history":[49.1,50.4,48.7,52.2,55.1,54.3,53.8],"drivers":[{"ticker":"AAPL","mentions":87,"buzz_score":69.7,"sentiment_score":0.22},{"ticker":"NVDA","mentions":76,"buzz_score":67.3,"sentiment_score":0.31}]}}},"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 Getnewsmarketsentiment"}}}},"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/news/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/news/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/news/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())"}]}},"/news/stocks/v1/stock/{ticker}/explain":{"get":{"tags":["News Stocks"],"summary":"AI explanation","description":"Returns an AI-generated explanation for why a stock is trending in the news dataset, anchored to article evidence.\n\n**Includes:**\n- `explanation`: 1-2 sentence summary of why the stock is trending\n- `cached`: whether this was served from cache\n- `generated_at`: when the explanation was generated\n- `model`: which LLM model generated the explanation","operationId":"getNewsStockExplanation","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 Getnewsstockexplanation"}}}},"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/news/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/news/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/news/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())"}]}},"/news/stocks/v1/compare":{"get":{"tags":["News Stocks"],"summary":"Compare stocks","description":"Compare multiple stock tickers side by side using the news sentiment dataset and buzz model.\n\nUse it when you already know the tickers and want a compact ranked table instead of full detail reports.\nResults are sorted by `buzz_score` descending and include `trend`, `trend_history`, `source_count`, `sentiment_score`, `bullish_pct` and `bearish_pct`.\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","operationId":"compareNewsStocks","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","maxLength":200,"description":"Comma-separated list of ticker symbols (e.g., 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/NewsCompareResponse"},"example":{"period_days":7,"stocks":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"source_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]},{"ticker":"NVDA","company_name":"NVIDIA Corporation","buzz_score":72.3,"trend":"stable","mentions":189,"source_count":6,"sentiment_score":0.45,"bullish_pct":51,"bearish_pct":16,"trend_history":[36.5,41.2,46.8,53.4,60.3,66.1,72.3]}]}}},"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 Comparenewsstocks"}}}},"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/news/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/news/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/news/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())"}]}},"/news/stocks/v1/search":{"get":{"tags":["News Stocks"],"summary":"Search stocks","description":"Search stocks by ticker, company name or alias in the News 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":"searchNewsStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":100,"description":"Search query (minimum 2 non-$ characters after trimming)","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/NewsSearchResponse"},"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":342,"buzz_score":87.5,"trend":"rising","sentiment_score":0.23,"bearish_pct":18,"bullish_pct":45,"source_count":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=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}}]}},"source_filter":{"summary":"Source filter is not supported on search","value":{"detail":[{"type":"extra_forbidden","loc":["query","source"],"msg":"Extra inputs are not permitted","input":"wsj"}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidSearchParametersError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Searchnewsstocks"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/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/news/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/news/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())"}]}},"/news/stocks/v1/stats":{"get":{"tags":["News Stocks"],"summary":"Service statistics","description":"Return high-level coverage statistics for the news stocks dataset.\n\nIncludes:\n- total mention rows stored\n- distinct tickers with news data\n- today's UTC mention and distinct ticker counts\n- total supported tickers in the reference universe","operationId":"getNewsStats","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsStatsResponse"},"example":{"total_mentions":12833,"unique_tickers":65,"mentions_today":342,"unique_tickers_today":21,"supported_tickers":11800}}},"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"}}}},"422":{"description":"Unsupported source filter query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"},"example":{"detail":[{"loc":["query","source"],"msg":"Extra inputs are not permitted","type":"extra_forbidden","input":"wsj"}]}}}}},"security":[{"ApiKeyAuth":[]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/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/news/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/news/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())"}]}},"/news/stocks/v1/stock/{ticker}/mentions":{"get":{"tags":["News Stocks"],"summary":"Raw Mentions","description":"Returns raw news mention rows for a specific stock ticker within the live raw-data retention window.\n**Professional account required.** Free and Hobby accounts cannot use this endpoint.\n\n**Use this endpoint when you need:**\n- article-level snippets\n- original timestamps\n- source attribution for raw rows\n\n**Notes:**\n- Use `from` and `to` for explicit UTC date windows\n- Results are ordered newest first and support deterministic `offset` + `limit` pagination\n- empty result sets return `200` with `results=[]`","operationId":"getNewsStockMentions","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)"},{"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 mentions to return","default":50,"title":"Limit"},"description":"Maximum number of raw mentions 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.","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/NewsRawMentionsResponse"},"example":{"ticker":"AAPL","period_days":7,"count":1,"results":[{"article_id":"news-123","source":"reuters","url":"https://example.com/article","title":"Apple supplier outlook lifts sentiment","summary":"Suppliers signaled stronger-than-expected demand...","text_snippet":"Suppliers signaled stronger-than-expected demand...","author":"Jane Doe","created_utc":"2026-03-20T09:03:00Z","sentiment_score":0.21,"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 Getnewsstockmentions"}}}},"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/news/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/news/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/news/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())"}]}},"/reddit/stocks/v1/health":{"get":{"tags":["Health-Check"],"summary":"Reddit Service Health","description":"Returns public health and freshness metadata for the Reddit stocks platform.\n\nUse it to check service availability, ingestion freshness and worker liveness.\nClient integrations usually start with `/trending`, `/stock/{ticker}` or `/search`.","operationId":"getHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"example":{"status":"healthy","service":"reddit-stocks","version":"1.49.0","total_mentions":12833,"tickers_tracked":65,"scheduler":{"running":true,"last_scrape":"2026-01-09T10:30:00Z","scrape_count":142,"error_count":3,"success_rate":0.979}}}},"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":"no-store"}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/stocks/v1/health\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/stocks/v1/health\");\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/reddit/stocks/v1/health\",\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/crypto/v1/health":{"get":{"tags":["Health-Check"],"summary":"Reddit Crypto Service Health","description":"Returns public health and freshness metadata for the Reddit crypto platform.\n\nUse it to check service availability, ingestion freshness and worker liveness.\nClient integrations usually start with `/trending`, `/token/{symbol}` or `/search`.","operationId":"getRedditCryptoHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoHealthResponse"},"example":{"status":"healthy","service":"reddit-crypto","version":"1.49.0","total_mentions":18352,"tokens_tracked":142,"scheduler":{"running":true,"last_scrape":"2026-03-12T07:55:00Z","scrape_count":248,"error_count":3,"success_rate":0.988,"timed_out_scrape_threads":0}}}},"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":"no-store"}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/crypto/v1/health\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/crypto/v1/health\");\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/reddit/crypto/v1/health\",\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/x/stocks/v1/health":{"get":{"tags":["Health-Check"],"summary":"X/Twitter Service Health","description":"Returns public health and freshness metadata for the X/Twitter stocks platform.\n\nUse it to check service availability, ingestion freshness and worker liveness.\nClient integrations usually start with `/trending`, `/stock/{ticker}` or `/search`.","operationId":"getXHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XHealthResponse"},"example":{"status":"healthy","service":"x-stocks","version":"1.49.0","total_mentions":15420,"tickers_tracked":247,"scheduler":{"running":true,"last_scrape":"2025-12-31T06:00:00Z","scrape_count":42,"error_count":2,"success_rate":0.95}}}},"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":"no-store"}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/x/stocks/v1/health\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/x/stocks/v1/health\");\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/health\",\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/polymarket/stocks/v1/health":{"get":{"tags":["Health-Check"],"summary":"Polymarket Service Health","description":"Returns public health and freshness metadata for the Polymarket stocks platform.\n\nUse it to check service availability, ingestion freshness and worker liveness.\nClient integrations usually start with `/trending`, `/stock/{ticker}` or `/search`.","operationId":"getPolymarketHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketHealthResponse"},"example":{"status":"healthy","service":"polymarket-stocks","version":"1.49.0","total_mentions":8421,"tickers_tracked":119,"scheduler":{"running":true,"last_scrape":"2026-02-18T10:00:00Z","scrape_count":58,"error_count":1,"success_rate":0.983}}}},"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":"no-store"}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/polymarket/stocks/v1/health\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/polymarket/stocks/v1/health\");\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/polymarket/stocks/v1/health\",\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/news/stocks/v1/health":{"get":{"tags":["Health-Check"],"summary":"News Service Health","description":"Returns public health and freshness metadata for the news stocks platform.\n\nUse it to check service availability, ingestion freshness and worker liveness.\nClient integrations usually start with `/trending`, `/stock/{ticker}` or `/search`.","operationId":"getNewsHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"example":{"status":"healthy","service":"reddit-stocks","version":"1.49.0","total_mentions":12833,"tickers_tracked":65,"scheduler":{"running":true,"last_scrape":"2026-01-09T10:30:00Z","scrape_count":142,"error_count":3,"success_rate":0.979}}}},"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":"no-store"}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/stocks/v1/health\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/news/stocks/v1/health\");\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/news/stocks/v1/health\",\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/health":{"get":{"tags":["Health-Check"],"summary":"Root Health","description":"Deep diagnostic health endpoint.\n\nDo not use this endpoint for Docker/Caddy liveness or deploy readiness; it\nintentionally includes heavier DB and worker freshness diagnostics.\nChild platform payloads that clearly report stale worker heartbeats via\nscheduler.running=false make the root diagnostic unhealthy.","operationId":"getRootHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootHealthResponse"},"example":{"status":"healthy","service":"adanos-api","version":"1.49.0","summary":{"total":5,"healthy":5,"unhealthy":0,"unhealthy_services":[]},"services":{"news-stocks":{"service":"news-stocks","status":"healthy","version":"1.49.0"},"polymarket-stocks":{"service":"polymarket-stocks","status":"healthy","version":"1.49.0"},"reddit-crypto":{"service":"reddit-crypto","status":"healthy","version":"1.49.0"},"reddit-stocks":{"service":"reddit-stocks","status":"healthy","version":"1.49.0"},"x-stocks":{"service":"x-stocks","status":"healthy","version":"1.49.0"}}}}},"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":"no-store"}}},"503":{"description":"One or more platform checks failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootHealthResponse"},"example":{"status":"healthy","service":"adanos-api","version":"1.49.0","summary":{"total":5,"healthy":5,"unhealthy":0,"unhealthy_services":[]},"services":{"news-stocks":{"service":"news-stocks","status":"healthy","version":"1.49.0"},"polymarket-stocks":{"service":"polymarket-stocks","status":"healthy","version":"1.49.0"},"reddit-crypto":{"service":"reddit-crypto","status":"healthy","version":"1.49.0"},"reddit-stocks":{"service":"reddit-stocks","status":"healthy","version":"1.49.0"},"x-stocks":{"service":"x-stocks","status":"healthy","version":"1.49.0"}}}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/health\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/health\");\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/health\",\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/sentiment/v1/analyze":{"post":{"tags":["Finance Sentiment"],"summary":"Analyze finance sentiment","description":"**Professional account required.** Free and Hobby accounts cannot use this endpoint.\n\nAnalyze a single financial or trading text using the Adanos finance-tuned sentiment engine.","operationId":"analyzeSentimentText","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SentimentAnalyzeRequest"},"example":{"text":"TSLA looks like a short squeeze setup, loading calls"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SentimentAnalyzeResponse"},"example":{"text":"TSLA looks like a short squeeze setup, loading calls","sentiment_score":0.78,"sentiment_label":"positive","components":{"engine_version":"5.4","vader_compound":0.34,"roberta_score":0.61,"emoji_score":0.0,"phrase_adjustment":0.21,"phrase_matches":[{"phrase":"short squeeze","score":3.5}],"contextual_finance_matches":[]}}}},"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"}}},"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":"Sentiment inference service unavailable","headers":{"Retry-After":{"description":"Seconds clients should wait before retrying","schema":{"type":"integer","example":5}}},"content":{"application/json":{"example":{"detail":"Sentiment inference service unavailable."}}}},"422":{"description":"Request body validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"},"example":{"detail":[{"loc":["body","text"],"msg":"String should have at least 1 character","type":"string_too_short","input":"","ctx":{"min_length":1}}]}}}},"403":{"description":"Professional account required","content":{"application/json":{"example":{"detail":{"error":"Professional account required","message":"This endpoint requires a Professional account. Upgrade to Professional: https://adanos.org/pricing","account_type":"free"}}}}}},"security":[{"ApiKeyAuth":[]}]}}},"components":{"schemas":{"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)."},"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."},"CompareResponse":{"properties":{"period_days":{"type":"integer","title":"Period Days","description":"Analysis period in days","examples":[7]},"stocks":{"items":{"$ref":"#/components/schemas/CompareStockItem"},"type":"array","title":"Stocks","description":"Stocks sorted by buzz_score descending"}},"type":"object","required":["period_days","stocks"],"title":"CompareResponse","description":"Comparison of multiple stocks.","examples":[{"period_days":7,"stocks":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"unique_posts":45,"subreddit_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"total_upvotes":15234,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]},{"ticker":"NVDA","company_name":"NVIDIA Corporation","buzz_score":72.3,"trend":"stable","mentions":189,"unique_posts":31,"subreddit_count":6,"sentiment_score":0.45,"bullish_pct":52,"bearish_pct":17,"total_upvotes":8921,"trend_history":[38.1,40.7,44.9,51.5,57.4,63.0,72.3]}]}]},"CompareStockItem":{"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":"Buzz Score (0-100). Asymptotic scaling above 50.","examples":[87.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, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today). Null when no qualifying Reddit data exists.","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total attributed mentions in period, including inherited thread-context mentions","examples":[342]},"unique_posts":{"type":"integer","title":"Unique Posts","description":"Number of unique posts in period","examples":[45]},"subreddit_count":{"type":"integer","title":"Subreddit Count","description":"Number of subreddits with mentions in period","examples":[8]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment (-1 to +1, null if no mentions)","examples":[0.23]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[45]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[18]},"total_upvotes":{"type":"integer","title":"Total Upvotes","description":"Total upvotes from attributed mentions","examples":[15234]},"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 when data exists. Empty when no qualifying data exists.","examples":[[45.2,52.1,48.7,67.3,72.1,78.4,87.5]]}},"type":"object","required":["ticker","buzz_score","mentions","unique_posts","subreddit_count","total_upvotes"],"title":"CompareStockItem","description":"Individual stock in comparison."},"CryptoCompareResponse":{"properties":{"period_days":{"type":"integer","title":"Period Days","description":"Analysis period in days","examples":[7]},"tokens":{"items":{"$ref":"#/components/schemas/CryptoCompareTokenItem"},"type":"array","title":"Tokens","description":"Requested tokens sorted by buzz_score descending"}},"type":"object","required":["period_days","tokens"],"title":"CryptoCompareResponse","description":"Comparison response for multiple crypto symbols.","examples":[{"period_days":7,"tokens":[{"symbol":"BTC","name":"Bitcoin","buzz_score":78.1,"trend":"rising","mentions":423,"unique_posts":97,"subreddit_count":12,"sentiment_score":0.31,"bullish_pct":47,"bearish_pct":18,"total_upvotes":15620,"trend_history":[42.3,46.8,51.2,58.9,64.0,71.4,78.1]},{"symbol":"ETH","name":"Ethereum","buzz_score":72.4,"trend":"stable","mentions":318,"unique_posts":73,"subreddit_count":9,"sentiment_score":0.27,"bullish_pct":43,"bearish_pct":19,"total_upvotes":10422,"trend_history":[36.2,41.4,46.7,53.1,60.2,66.5,72.4]}]}]},"CryptoCompareTokenItem":{"properties":{"symbol":{"type":"string","title":"Symbol","examples":["BTC"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","examples":["Bitcoin"]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","examples":[78.1]},"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, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today). Null when no qualifying data exists.","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Attributed mentions in the selected period, including inherited thread-context mentions","examples":[423]},"unique_posts":{"type":"integer","title":"Unique Posts","description":"Unique Reddit post count","examples":[97]},"subreddit_count":{"type":"integer","title":"Subreddit Count","description":"Unique subreddit count","examples":[12]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","examples":[0.31]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","examples":[47]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","examples":[18]},"total_upvotes":{"type":"integer","title":"Total Upvotes","description":"Total upvotes from attributed mentions","examples":[15620]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values when data exists. Empty when no qualifying data exists.","examples":[[42.3,46.8,51.2,58.9,64.0,71.4,78.1]]}},"type":"object","required":["symbol","buzz_score","mentions","unique_posts","subreddit_count","total_upvotes"],"title":"CryptoCompareTokenItem","description":"Individual crypto token in a compare response."},"CryptoDailyTrendItem":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Date in YYYY-MM-DD format","examples":["2026-02-24"]},"mentions":{"type":"integer","title":"Mentions","description":"Attributed mention count for the day, including inherited thread-context mentions","examples":[84]},"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.22]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Daily buzz score","examples":[56.4]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Bullish mention percentage for the day, calculated from positive sentiment-classified mentions","examples":[58]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Bearish mention percentage for the day, calculated from negative sentiment-classified mentions","examples":[22]}},"type":"object","required":["date","mentions"],"title":"CryptoDailyTrendItem","description":"Daily trend datapoint for a crypto symbol."},"CryptoHealthResponse":{"properties":{"status":{"type":"string","title":"Status","examples":["healthy"]},"service":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service","examples":["reddit-crypto"]},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","examples":["1.49.0"]},"total_mentions":{"type":"integer","title":"Total Mentions","description":"Mentions observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable.","default":0},"tokens_tracked":{"type":"integer","title":"Tokens Tracked","description":"Distinct symbols observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable.","default":0},"scheduler":{"anyOf":[{"$ref":"#/components/schemas/CryptoSchedulerStatus"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["status"],"title":"CryptoHealthResponse","description":"Health response for Reddit Crypto service.","examples":[{"status":"healthy","service":"reddit-crypto","version":"1.49.0","total_mentions":18352,"tokens_tracked":142,"scheduler":{"running":true,"last_scrape":"2026-03-12T07:55:00Z","scrape_count":248,"error_count":3,"success_rate":0.988,"timed_out_scrape_threads":0}}]},"CryptoMarketSentimentDriver":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Crypto symbol","examples":["BTC"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Attributed Reddit mentions in the selected period, including inherited thread-context mentions","examples":[423]},"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":[78.1]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for this asset","examples":[0.31]}},"type":"object","required":["symbol","mentions","buzz_score"],"title":"CryptoMarketSentimentDriver","description":"Top asset contributing to the service-level Reddit Crypto market sentiment."},"CryptoMarketSentimentResponse":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Service-wide Reddit Crypto heat score relative to the trailing 90-day baseline for the selected period","examples":[52.4]},"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, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Total Reddit mentions across the selected period, including inherited thread-context mentions","examples":[5412]},"unique_posts":{"type":"integer","minimum":0.0,"title":"Unique Posts","description":"Exact distinct Reddit post count across the selected UTC period","examples":[1184]},"subreddit_count":{"type":"integer","minimum":0.0,"title":"Subreddit Count","description":"Distinct subreddits contributing in the selected period","examples":[37]},"total_upvotes":{"type":"integer","minimum":0.0,"title":"Total Upvotes","description":"Total upvotes across attributed mentions in the selected period","examples":[41290]},"active_tickers":{"type":"integer","minimum":0.0,"title":"Active Tickers","description":"Number of crypto symbols with activity in the selected period","examples":[89]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Service-wide average sentiment score across the selected period","examples":[0.117]},"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":[2101]},"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":[1318]},"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":[1993]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Bullish mention percentage","examples":[39]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Bearish mention percentage","examples":[24]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily service-wide Reddit Crypto heat scores (oldest→newest), each calibrated relative to the trailing 90-day baseline. Length = max(requested_days, 7) for successful requests; windows before platform availability return HTTP 422.","examples":[[47.1,49.3,50.4,52.2,51.8,53.0,52.4]]},"drivers":{"items":{"$ref":"#/components/schemas/CryptoMarketSentimentDriver"},"type":"array","title":"Drivers","description":"Top assets by current buzz_score driving the service-level reading"}},"type":"object","required":["buzz_score","mentions","unique_posts","subreddit_count","total_upvotes","active_tickers","positive_count","negative_count","neutral_count","bullish_pct","bearish_pct"],"title":"CryptoMarketSentimentResponse","description":"Service-level Reddit Crypto market sentiment across all tracked assets.","examples":[{"buzz_score":52.4,"trend":"stable","mentions":5412,"unique_posts":1184,"subreddit_count":37,"total_upvotes":41290,"active_tickers":89,"sentiment_score":0.117,"positive_count":2101,"negative_count":1318,"neutral_count":1993,"bullish_pct":39,"bearish_pct":24,"trend_history":[47.1,49.3,50.4,52.2,51.8,53.0,52.4],"drivers":[{"symbol":"BTC","mentions":423,"buzz_score":78.1,"sentiment_score":0.31},{"symbol":"ETH","mentions":318,"buzz_score":72.4,"sentiment_score":0.27}]}]},"CryptoRawMentionItem":{"properties":{"post_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Post Id","description":"Reddit post identifier","examples":["abc123"]},"comment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment Id","description":"Reddit comment identifier when the mention comes from a comment","examples":["def456"]},"subreddit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subreddit","description":"Source subreddit","examples":["cryptocurrency"]},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Public Reddit author name, if scraped","examples":["deepfuckingvalue"]},"text_snippet":{"type":"string","title":"Text Snippet","description":"Stored mention snippet (truncated at ingestion time)","examples":["BTC still looks strong above this range..."]},"created_utc":{"type":"string","format":"date-time","title":"Created Utc","description":"ISO timestamp of creation","examples":["2026-03-20T18:42:10Z"]},"upvotes":{"type":"integer","title":"Upvotes","description":"Reddit score (upvotes) for this mention row","examples":[381]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Sentiment score (-1 to +1)","examples":[0.62]},"sentiment_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentiment Label","description":"Sentiment label (positive/negative/neutral)","examples":["positive"]},"is_inherited":{"type":"boolean","title":"Is Inherited","description":"Whether symbol context was inherited from the parent thread instead of directly mentioned","examples":[false]}},"type":"object","required":["text_snippet","created_utc","upvotes","is_inherited"],"title":"CryptoRawMentionItem","description":"Raw Reddit crypto mention row for one symbol."},"CryptoRawMentionsResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Crypto symbol","examples":["BTC"]},"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 for the requested include_inherited filter before limit and offset are applied; only the requested page is returned","examples":[1]},"results":{"items":{"$ref":"#/components/schemas/CryptoRawMentionItem"},"type":"array","title":"Results","description":"Raw mention rows ordered by newest first"}},"type":"object","required":["symbol","period_days","count","results"],"title":"CryptoRawMentionsResponse","description":"Paginated raw Reddit crypto mentions for a single symbol.","examples":[{"symbol":"BTC","period_days":7,"count":1,"results":[{"post_id":"abc123","comment_id":"def456","subreddit":"cryptocurrency","author":"user123","text_snippet":"BTC still looks strong above this range...","created_utc":"2026-03-20T18:42:10Z","upvotes":381,"sentiment_score":0.62,"sentiment_label":"positive","is_inherited":false}]}]},"CryptoSchedulerStatus":{"properties":{"running":{"type":"boolean","title":"Running","description":"Whether worker heartbeat is fresh"},"last_scrape":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Scrape","description":"Last scrape timestamp"},"scrape_count":{"type":"integer","title":"Scrape Count","description":"Total scrapes","default":0},"error_count":{"type":"integer","title":"Error Count","description":"Total failed scrapes","default":0},"success_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Success Rate","description":"Success ratio"},"timed_out_scrape_threads":{"type":"integer","title":"Timed Out Scrape Threads","description":"Timed-out Tor scrape attempts observed since the last successful reset.","default":0},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Additional status information"}},"type":"object","required":["running"],"title":"CryptoSchedulerStatus","description":"Crypto worker heartbeat status."},"CryptoSearchItem":{"properties":{"symbol":{"type":"string","title":"Symbol","examples":["SOL"]},"name":{"type":"string","title":"Name","examples":["Solana"]},"market_cap_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Market Cap Rank","examples":[6]},"market_cap_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Cap Usd","examples":[71234567890.12]},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","examples":[["Sol"]]},"summary":{"$ref":"#/components/schemas/CryptoSearchSummary","description":"Last-7-days Reddit summary for this asset"}},"type":"object","required":["symbol","name","summary"],"title":"CryptoSearchItem","description":"Single search result for crypto reference data."},"CryptoSearchResponse":{"properties":{"query":{"type":"string","title":"Query","description":"Original search query","examples":["solana"]},"count":{"type":"integer","title":"Count","description":"Total number of matching assets 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/CryptoSearchItem"},"type":"array","title":"Results","description":"Top matching crypto assets capped by the requested limit"}},"type":"object","required":["query","count","period_days","results"],"title":"CryptoSearchResponse","description":"Search response for crypto assets.","examples":[{"query":"solana","count":1,"period_days":7,"results":[{"symbol":"SOL","name":"Solana","market_cap_rank":6,"market_cap_usd":71234567890.12,"aliases":["Sol"],"summary":{"mentions":287,"buzz_score":72.4,"trend":"stable","sentiment_score":0.27,"bearish_pct":19,"bullish_pct":43,"subreddit_count":9,"total_upvotes":10422,"unique_posts":73}}]}]},"CryptoSearchSummary":{"properties":{"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Attributed mentions in the last 7 UTC calendar days, including inherited thread-context mentions","examples":[287]},"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.4]},"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, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["stable"]},"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.27]}},"type":"object","required":["mentions","buzz_score"],"title":"CryptoSearchSummary","description":"Compact last-7-days summary attached to crypto search results."},"CryptoStatsResponse":{"properties":{"total_mentions":{"type":"integer","title":"Total Mentions","description":"Rollup-backed all-time Reddit Crypto mention total; current-day raw rows may be used only as a bounded freshness fallback","examples":[18352]},"unique_tokens":{"type":"integer","title":"Unique Tokens","examples":[142]},"mentions_today":{"type":"integer","title":"Mentions Today","default":0,"examples":[287]},"unique_tokens_today":{"type":"integer","title":"Unique Tokens Today","default":0,"examples":[35]},"supported_tokens":{"type":"integer","title":"Supported Tokens","examples":[500]}},"type":"object","required":["total_mentions","unique_tokens","supported_tokens"],"title":"CryptoStatsResponse","description":"High-level crypto dataset statistics.","examples":[{"total_mentions":18352,"unique_tokens":142,"mentions_today":287,"unique_tokens_today":35,"supported_tokens":500}]},"CryptoSubredditCount":{"properties":{"subreddit":{"type":"string","title":"Subreddit","description":"Subreddit name","examples":["cryptocurrency"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Attributed mentions in this subreddit","examples":[89]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for this subreddit in the selected period","examples":[0.22]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Contributor-level buzz score for this subreddit in the selected period","examples":[61.5]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Deprecated alias for mentions. Use mentions instead.","deprecated":true,"examples":[89]}},"type":"object","required":["subreddit","mentions","count"],"title":"CryptoSubredditCount","description":"Subreddit contributor metrics for a crypto detail response."},"CryptoTokenSentiment":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Token symbol","examples":["ETH"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Token name","examples":["Ethereum"]},"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.","deprecated":true},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score"},"mentions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentions","description":"Attributed mentions in the selected period, including inherited thread-context mentions","examples":[318]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment"},"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 upvotes from attributed mentions"},"unique_posts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Unique Posts","description":"Distinct post count"},"subreddit_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Subreddit Count","description":"Distinct subreddit count"},"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, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)."},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Bullish mention percentage"},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Bearish mention percentage"},"period_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Period Days","description":"Analysis period in days"},"top_subreddits":{"anyOf":[{"items":{"$ref":"#/components/schemas/CryptoSubredditCount"},"type":"array"},{"type":"null"}],"title":"Top Subreddits","description":"Top subreddits by mentions"},"daily_trend":{"anyOf":[{"items":{"$ref":"#/components/schemas/CryptoDailyTrendItem"},"type":"array"},{"type":"null"}],"title":"Daily Trend","description":"Daily attributed mention breakdown for the selected period, with sentiment and buzz_score"},"top_mentions":{"anyOf":[{"items":{"$ref":"#/components/schemas/CryptoTopMention"},"type":"array"},{"type":"null"}],"title":"Top Mentions","description":"Top explicit mentions from the selected period, ranked by engagement"}},"type":"object","required":["symbol","found"],"title":"CryptoTokenSentiment","description":"Detailed Reddit sentiment for a single crypto symbol.","examples":[{"symbol":"ETH","name":"Ethereum","found":true,"buzz_score":72.4,"mentions":318,"sentiment_score":0.27,"total_upvotes":10422,"unique_posts":73,"subreddit_count":9,"trend":"stable","bullish_pct":43,"bearish_pct":19,"period_days":7,"top_subreddits":[{"subreddit":"ethtrader","mentions":91,"count":91},{"subreddit":"cryptocurrency","mentions":84,"count":84}],"daily_trend":[{"date":"2026-02-24","mentions":48,"sentiment_score":0.22,"buzz_score":56.4,"bullish_pct":58,"bearish_pct":21},{"date":"2026-02-23","mentions":42,"sentiment_score":0.19,"buzz_score":51.7,"bullish_pct":52,"bearish_pct":24}],"top_mentions":[{"text_snippet":"ETH setup still looks strong into the next catalyst.","sentiment_score":0.74,"sentiment_label":"positive","upvotes":1200,"subreddit":"ethtrader","created_utc":"2026-02-24T09:15:00Z"}]}]},"CryptoTopMention":{"properties":{"text_snippet":{"type":"string","title":"Text Snippet","description":"Mention text snippet"},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Sentiment score (-1 to +1)"},"sentiment_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentiment Label","description":"Sentiment label"},"upvotes":{"type":"integer","title":"Upvotes","description":"Upvote count","examples":[1200]},"subreddit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subreddit","description":"Source subreddit","examples":["cryptocurrency"]},"created_utc":{"type":"string","format":"date-time","title":"Created Utc","description":"ISO timestamp"}},"type":"object","required":["text_snippet","upvotes","created_utc"],"title":"CryptoTopMention","description":"Top Reddit mention ordered by engagement."},"CryptoTrendingToken":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Token symbol","examples":["BTC"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Token name","examples":["Bitcoin"]},"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Buzz score (0-100)","examples":[78.1]},"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, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)."},"mentions":{"type":"integer","title":"Mentions","description":"Attributed mention count, including inherited thread-context mentions","examples":[423]},"unique_posts":{"type":"integer","title":"Unique Posts","description":"Unique Reddit post count","examples":[97]},"subreddit_count":{"type":"integer","title":"Subreddit Count","description":"Unique subreddit count","examples":[12]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Average sentiment score","examples":[0.31]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Bullish mention percentage","examples":[47]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Bearish mention percentage","examples":[18]},"total_upvotes":{"type":"integer","title":"Total Upvotes","description":"Total upvotes from attributed mentions","examples":[15620]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values."}},"type":"object","required":["symbol","buzz_score","trend","mentions","unique_posts","subreddit_count","sentiment_score","bullish_pct","bearish_pct","total_upvotes"],"title":"CryptoTrendingToken","description":"Trending crypto token summary.","examples":[{"symbol":"BTC","name":"Bitcoin","buzz_score":78.1,"trend":"rising","mentions":423,"unique_posts":97,"subreddit_count":12,"sentiment_score":0.31,"bullish_pct":47,"bearish_pct":18,"total_upvotes":15620,"trend_history":[42.3,46.8,51.2,58.9,64.0,71.4,78.1]}]},"DailyTrendItem":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Date in YYYY-MM-DD format","examples":["2025-12-28"]},"mentions":{"type":"integer","title":"Mentions","description":"Attributed mention count for this date, including inherited thread-context mentions","examples":[52]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for this date","examples":[0.31]},"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":[42.8]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Bullish mention percentage for this date, calculated from positive sentiment-classified mentions","examples":[62]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Bearish mention percentage for this date, calculated from negative sentiment-classified mentions","examples":[18]}},"type":"object","required":["date","mentions"],"title":"DailyTrendItem","description":"Daily trend data point."},"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"}]},"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"}]}]},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Current health status","examples":["healthy"]},"service":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service","description":"Service identifier","examples":["reddit-stocks"]},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","description":"Service version","examples":["1.49.0"]},"total_mentions":{"type":"integer","title":"Total Mentions","description":"Mentions observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable.","default":0,"examples":[12833]},"tickers_tracked":{"type":"integer","title":"Tickers Tracked","description":"Distinct tickers observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable.","default":0,"examples":[65]},"scheduler":{"anyOf":[{"$ref":"#/components/schemas/SchedulerStatus"},{"type":"null"}],"description":"Scheduler status information"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if unhealthy"}},"type":"object","required":["status"],"title":"HealthResponse","description":"API health status.","examples":[{"status":"healthy","service":"reddit-stocks","version":"1.49.0","total_mentions":12833,"tickers_tracked":65,"scheduler":{"running":true,"last_scrape":"2026-01-09T10:30:00Z","scrape_count":142,"error_count":3,"success_rate":0.979}}]},"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)."},"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."},"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)."},"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."},"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."},"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."},"NewsCompareResponse":{"properties":{"period_days":{"type":"integer","title":"Period Days","description":"Analysis period in days","examples":[7]},"stocks":{"items":{"$ref":"#/components/schemas/NewsCompareStockItem"},"type":"array","title":"Stocks","description":"Stocks sorted by buzz_score descending"}},"type":"object","required":["period_days","stocks"],"title":"NewsCompareResponse","description":"Comparison of multiple stocks in news.","examples":[{"period_days":7,"stocks":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"source_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]},{"ticker":"NVDA","company_name":"NVIDIA Corporation","buzz_score":72.3,"trend":"stable","mentions":189,"source_count":6,"sentiment_score":0.45,"bullish_pct":51,"bearish_pct":16,"trend_history":[36.5,41.2,46.8,53.4,60.3,66.1,72.3]}]}]},"NewsCompareStockItem":{"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":"Buzz Score (0-100). Asymptotic scaling above 50.","examples":[87.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/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today). Null when no qualifying news data exists.","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total mentions in period","examples":[342]},"source_count":{"type":"integer","title":"Source Count","description":"Number of distinct news sources with mentions in period","examples":[8]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment (-1 to +1, null if no mentions)","examples":[0.23]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[45]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[18]},"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 when data exists. Empty when no qualifying data exists.","examples":[[45.2,52.1,48.7,67.3,72.1,78.4,87.5]]}},"type":"object","required":["ticker","buzz_score","mentions","source_count"],"title":"NewsCompareStockItem","description":"Individual stock in news comparison."},"NewsMarketSentimentDriver":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["AAPL"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"News mentions in the selected period","examples":[87]},"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":[69.7]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average news sentiment score for this asset","examples":[0.22]}},"type":"object","required":["ticker","mentions","buzz_score"],"title":"NewsMarketSentimentDriver","description":"Top asset contributing to the service-level News market sentiment."},"NewsMarketSentimentResponse":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Service-wide News heat score relative to the service's trailing 90-day baseline. Around 50 = normal coverage heat, higher values = hotter-than-usual coverage.","examples":[53.8]},"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/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["stable"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"News mentions across the selected period","examples":[1298]},"unique_articles":{"type":"integer","minimum":0.0,"title":"Unique Articles","description":"Exact distinct article count across the selected UTC period","examples":[911]},"source_count":{"type":"integer","minimum":0.0,"title":"Source Count","description":"Exact distinct news-source breadth across the selected UTC period","examples":[44]},"active_tickers":{"type":"integer","minimum":0.0,"title":"Active Tickers","description":"Number of tickers with news activity in the selected period","examples":[233]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Service-wide average news sentiment score","examples":[0.064]},"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":[512]},"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":[308]},"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":[478]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Bullish news mention percentage","examples":[39]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Bearish news mention percentage","examples":[24]},"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":[[49.1,50.4,48.7,52.2,55.1,54.3,53.8]]},"drivers":{"items":{"$ref":"#/components/schemas/NewsMarketSentimentDriver"},"type":"array","title":"Drivers","description":"Top assets by current buzz_score driving the service-level reading"}},"type":"object","required":["buzz_score","mentions","unique_articles","source_count","active_tickers","positive_count","negative_count","neutral_count","bullish_pct","bearish_pct"],"title":"NewsMarketSentimentResponse","description":"Service-level News market sentiment across all tracked stocks.","examples":[{"buzz_score":53.8,"trend":"stable","mentions":1298,"unique_articles":911,"source_count":44,"active_tickers":233,"sentiment_score":0.064,"positive_count":512,"negative_count":308,"neutral_count":478,"bullish_pct":39,"bearish_pct":24,"trend_history":[49.1,50.4,48.7,52.2,55.1,54.3,53.8],"drivers":[{"ticker":"AAPL","mentions":87,"buzz_score":69.7,"sentiment_score":0.22},{"ticker":"NVDA","mentions":76,"buzz_score":67.3,"sentiment_score":0.31}]}]},"NewsRawMentionItem":{"properties":{"article_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Article Id","description":"Article identifier when available","examples":["news-123"]},"source":{"type":"string","title":"Source","description":"Source publication identifier","examples":["reuters"]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Article URL","examples":["https://example.com/article"]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Article title","examples":["Apple supplier outlook lifts sentiment"]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"Article summary","examples":["Suppliers signaled stronger-than-expected demand..."]},"text_snippet":{"type":"string","title":"Text Snippet","description":"Stored article snippet (truncated at ingestion time)","examples":["Suppliers signaled stronger-than-expected demand..."]},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Public article author/byline when available","examples":["Jane Doe"]},"created_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created Utc","description":"ISO timestamp of creation when available","examples":["2026-03-20T09:03:00Z"]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Sentiment score (-1 to +1)","examples":[0.21]},"sentiment_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentiment Label","description":"Sentiment label (positive/negative/neutral)","examples":["positive"]}},"type":"object","required":["source","text_snippet"],"title":"NewsRawMentionItem","description":"Raw news mention row for one stock ticker."},"NewsRawMentionsResponse":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["AAPL"]},"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/NewsRawMentionItem"},"type":"array","title":"Results","description":"Raw news mention rows ordered by newest first"}},"type":"object","required":["ticker","period_days","count","results"],"title":"NewsRawMentionsResponse","description":"Paginated raw news mentions for a single stock ticker.","examples":[{"ticker":"AAPL","period_days":7,"count":1,"results":[{"article_id":"news-123","source":"reuters","url":"https://example.com/article","title":"Apple supplier outlook lifts sentiment","summary":"Suppliers signaled stronger-than-expected demand...","text_snippet":"Suppliers signaled stronger-than-expected demand...","author":"Jane Doe","created_utc":"2026-03-20T09:03:00Z","sentiment_score":0.21,"sentiment_label":"positive"}]}]},"NewsSearchResponse":{"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/NewsSearchResultItem"},"type":"array","title":"Results","description":"Top matching stocks capped by the requested limit"}},"type":"object","required":["query","count","period_days","results"],"title":"NewsSearchResponse","description":"Search response for news assets.","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":342,"buzz_score":87.5,"trend":"rising","sentiment_score":0.23,"bearish_pct":18,"bullish_pct":45,"source_count":8}}]}]},"NewsSearchResultItem":{"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 (NYSE, NASDAQ, etc.)","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/NewsSearchSummary","description":"Last-7-days news summary for this asset"}},"type":"object","required":["ticker","name","summary"],"title":"NewsSearchResultItem","description":"Individual news search result item."},"NewsSearchSummary":{"properties":{"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"News mentions in the last 7 UTC calendar days","examples":[342]},"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":[87.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/articles and source breadth; not price 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.23]}},"type":"object","required":["mentions","buzz_score"],"title":"NewsSearchSummary","description":"Compact last-7-days summary attached to news search results."},"NewsSourceCount":{"properties":{"source":{"type":"string","title":"Source","description":"News source identifier","examples":["reuters"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Mentions from this source","examples":[89]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for this source in the selected period","examples":[0.21]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Contributor-level buzz score for this source in the selected period","examples":[58.4]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Deprecated alias for mentions. Use mentions instead.","deprecated":true,"examples":[89]}},"type":"object","required":["source","mentions","count"],"title":"NewsSourceCount","description":"News source contributor metrics for a stock detail response."},"NewsStatsResponse":{"properties":{"total_mentions":{"type":"integer","title":"Total Mentions","description":"Rollup-backed all-time news stock mention total; current-day raw rows may be used only as a bounded freshness fallback","examples":[12833]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers with news mentions","examples":[65]},"mentions_today":{"type":"integer","title":"Mentions Today","description":"News mention rows created since today's UTC midnight","default":0,"examples":[342]},"unique_tickers_today":{"type":"integer","title":"Unique Tickers Today","description":"Unique tickers with news mention rows since today's UTC midnight","default":0,"examples":[21]},"supported_tickers":{"type":"integer","title":"Supported Tickers","description":"Number of supported ticker patterns (from ticker_reference)","examples":[11800]}},"type":"object","required":["total_mentions","unique_tickers","supported_tickers"],"title":"NewsStatsResponse","description":"News service statistics.","examples":[{"total_mentions":12833,"unique_tickers":65,"mentions_today":342,"unique_tickers_today":21,"supported_tickers":11800}]},"NewsStockSentiment":{"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 (null if not found)","examples":["Tesla, Inc."]},"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.","deprecated":true},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz Score (0-100). Asymptotic scaling above 50.","examples":[87.5]},"mentions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentions","description":"Total mentions in the selected period","examples":[342]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score (-1 bearish to +1 bullish)","examples":[0.23]},"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,"examples":[154]},"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,"examples":[62]},"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,"examples":[126]},"source_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Source Count","description":"Number of sources with mentions","examples":[8]},"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/articles and source breadth; not price 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 mentions","examples":[45]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[18]},"period_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Period Days","description":"Analysis period in days","examples":[7]},"top_sources":{"anyOf":[{"items":{"$ref":"#/components/schemas/NewsSourceCount"},"type":"array"},{"type":"null"}],"title":"Top Sources","description":"Top sources by mention count"},"daily_trend":{"anyOf":[{"items":{"$ref":"#/components/schemas/DailyTrendItem"},"type":"array"},{"type":"null"}],"title":"Daily Trend","description":"Daily mention breakdown for the selected period, with sentiment and buzz_score"},"top_mentions":{"anyOf":[{"items":{"$ref":"#/components/schemas/NewsTopMention"},"type":"array"},{"type":"null"}],"title":"Top Mentions","description":"Top news mentions from the selected period, ranked by recency"}},"type":"object","required":["ticker","found"],"title":"NewsStockSentiment","description":"Detailed sentiment analysis for a specific stock ticker from news mentions.","examples":[{"ticker":"TSLA","company_name":"Tesla, Inc.","found":true,"buzz_score":87.5,"mentions":342,"sentiment_score":0.23,"source_count":8,"trend":"rising","bullish_pct":45,"bearish_pct":18,"period_days":7,"top_sources":[{"source":"reuters","mentions":89,"count":89},{"source":"benzinga","mentions":67,"count":67}],"daily_trend":[{"date":"2026-03-05","mentions":52,"sentiment_score":0.31,"buzz_score":42.8,"bullish_pct":58,"bearish_pct":19},{"date":"2026-03-04","mentions":48,"sentiment_score":0.18,"buzz_score":38.5,"bullish_pct":46,"bearish_pct":21}],"top_mentions":[{"text_snippet":"TSLA looking strong after production update...","sentiment_score":0.85,"sentiment_label":"positive","source":"reuters","created_utc":"2026-03-05T10:30:00+00:00"}]}]},"NewsTopMention":{"properties":{"text_snippet":{"type":"string","title":"Text Snippet","description":"Excerpt from the mention","examples":["NVIDIA earnings beat expectations..."]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Sentiment score (-1 to +1)","examples":[0.73]},"sentiment_label":{"type":"string","title":"Sentiment Label","description":"Sentiment label (positive/negative/neutral)","examples":["positive"]},"source":{"type":"string","title":"Source","description":"Source publication identifier","examples":["reuters"]},"created_utc":{"type":"string","title":"Created Utc","description":"ISO timestamp of creation","examples":["2026-03-05T12:30:00+00:00"]}},"type":"object","required":["text_snippet","sentiment_score","sentiment_label","source","created_utc"],"title":"NewsTopMention","description":"Top mention item from news."},"NewsTrendingCountry":{"properties":{"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Aggregated Buzz Score (0-100)","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/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total mentions","examples":[4523]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers mentioned","examples":[34]},"source_count":{"type":"integer","title":"Source Count","description":"Number of distinct news sources with mentions","examples":[15]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Weighted average sentiment (-1 bearish to +1 bullish)","examples":[0.28]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[54]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[22]},"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`.","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 mentions","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","source_count","sentiment_score","bullish_pct","bearish_pct","trend_history","top_tickers","country"],"title":"NewsTrendingCountry","description":"Trending country with aggregated buzz metrics from news.","examples":[{"buzz_score":82.3,"trend":"stable","mentions":8934,"unique_tickers":156,"source_count":18,"sentiment_score":0.21,"bullish_pct":48,"bearish_pct":26,"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"}]},"NewsTrendingSector":{"properties":{"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Aggregated Buzz Score (0-100)","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/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total mentions","examples":[4523]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers mentioned","examples":[34]},"source_count":{"type":"integer","title":"Source Count","description":"Number of distinct news sources with mentions","examples":[15]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Weighted average sentiment (-1 bearish to +1 bullish)","examples":[0.28]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[54]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[22]},"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`.","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 mentions","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","source_count","sentiment_score","bullish_pct","bearish_pct","trend_history","top_tickers","sector"],"title":"NewsTrendingSector","description":"Trending sector with aggregated buzz metrics from news.","examples":[{"buzz_score":78.4,"trend":"rising","mentions":4523,"unique_tickers":34,"source_count":15,"sentiment_score":0.28,"bullish_pct":54,"bearish_pct":22,"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"}]},"NewsTrendingStock":{"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 (null if not found)","examples":["Tesla, Inc."]},"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Buzz Score (0-100). Asymptotic scaling above 50.","examples":[87.5]},"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/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total number of mentions","examples":[342]},"source_count":{"type":"integer","title":"Source Count","description":"Number of distinct news sources with mentions","examples":[8]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Average sentiment score (-1 bearish to +1 bullish)","examples":[0.23]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[45]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[18]},"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. Values 0-100.","examples":[[12.3,15.2,18.7,22.1,28.5,35.2,42.8]]}},"type":"object","required":["ticker","buzz_score","trend","mentions","source_count","sentiment_score","bullish_pct","bearish_pct"],"title":"NewsTrendingStock","description":"Trending stock with buzz metrics from news sources.","examples":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"source_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]}]},"PolymarketCompareResponse":{"properties":{"period_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Period Days","description":"Analysis period in days"},"stocks":{"items":{"$ref":"#/components/schemas/PolymarketCompareStockItem"},"type":"array","title":"Stocks","description":"Stocks sorted by buzz_score descending"}},"type":"object","required":["period_days","stocks"],"title":"PolymarketCompareResponse","description":"Response for compare endpoint.","examples":[{"period_days":7,"stocks":[{"ticker":"AAPL","company_name":"Apple Inc.","buzz_score":68.9,"trend":"stable","trade_count":312,"market_count":27,"current_market_count":12,"unique_traders":119,"sentiment_score":0.28,"bullish_pct":64,"bearish_pct":36,"total_liquidity":128000.0,"trend_history":[48.2,51.0,55.3,61.1,65.8,69.2,68.9]}]}]},"PolymarketCompareStockItem":{"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"},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score (0-100)"},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today). Null when no qualifying activity exists."},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Trade count in selected period"},"market_count":{"type":"integer","minimum":0.0,"title":"Market Count","description":"Distinct markets that existed for ticker within the selected UTC window, counted by market-catalog lifetime overlap"},"current_market_count":{"type":"integer","minimum":0.0,"title":"Current Market Count","description":"Number of currently open markets in the latest UTC-day snapshot for ticker; use this for live-only market breadth"},"unique_traders":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Unique Traders","description":"Exact distinct union of observed proxy and explicit maker wallet hashes for the delivered scope and UTC window; null when retained wallet-level trades do not fully cover the window; not a complete market-wide participant census"},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Orderbook-aware implied sentiment; null when no directional sentiment evidence exists in the selected period"},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Outcome-aware bullish market percentage"},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Outcome-aware bearish market percentage"},"total_liquidity":{"type":"number","minimum":0.0,"title":"Total Liquidity","description":"Windowed aggregated liquidity signal in USD over the selected period; not a current snapshot"},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Recent buzz history (oldest→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."}},"type":"object","required":["ticker","buzz_score","trade_count","market_count","current_market_count","total_liquidity"],"title":"PolymarketCompareStockItem","description":"Single stock item for Polymarket compare endpoint."},"PolymarketDailyTrendItem":{"properties":{"date":{"type":"string","title":"Date","description":"Date in YYYY-MM-DD format","examples":["2026-02-13"]},"trade_count":{"type":"integer","title":"Trade Count","description":"Trade count on this date","examples":[5]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Outcome-aware implied sentiment on this date; can come from orderbook evidence or legacy traded price evidence, null when no sentiment evidence exists","examples":[0.25]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score on this date; null when neither a daily aggregate nor a live fallback could be computed for this date","examples":[64.1]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Outcome-aware bullish market-direction percentage for this date","examples":[64]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Outcome-aware bearish market-direction percentage for this date","examples":[21]}},"type":"object","required":["date","trade_count"],"title":"PolymarketDailyTrendItem","description":"Daily trend item for stock detail endpoint."},"PolymarketHealthResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Current health status","examples":["healthy"]},"service":{"type":"string","title":"Service","description":"Service identifier","examples":["polymarket-stocks"]},"version":{"type":"string","title":"Version","description":"API version","examples":["1.49.0"]},"total_mentions":{"type":"integer","minimum":0.0,"title":"Total Mentions","description":"Mentions observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable."},"tickers_tracked":{"type":"integer","minimum":0.0,"title":"Tickers Tracked","description":"Distinct tickers observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable."},"scheduler":{"anyOf":[{"$ref":"#/components/schemas/PolymarketSchedulerStatus"},{"type":"null"}],"description":"Polymarket worker status"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message when unhealthy"}},"type":"object","required":["status","service","version","total_mentions","tickers_tracked"],"title":"PolymarketHealthResponse","description":"Polymarket health response.","examples":[{"status":"healthy","service":"polymarket-stocks","version":"1.49.0","total_mentions":8421,"tickers_tracked":119,"scheduler":{"running":true,"last_scrape":"2026-02-18T10:00:00Z","scrape_count":58,"error_count":1,"success_rate":0.983}}]},"PolymarketMarketSentimentDriver":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["AAPL"]},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Trade count for this asset in the selected period","examples":[52]},"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":[68.9]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Implied sentiment score for this asset in the selected period","examples":[0.28]}},"type":"object","required":["ticker","trade_count","buzz_score"],"title":"PolymarketMarketSentimentDriver","description":"Top asset contributing to the service-level Polymarket market sentiment."},"PolymarketMarketSentimentResponse":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Service-wide Polymarket heat score relative to the service's trailing 90-day baseline. Around 50 = normal activity, higher values = hotter-than-usual Polymarket activity.","examples":[58.4]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. Null when the selected window has no measurable Polymarket heat. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Service-wide trade count in the selected period","examples":[512]},"market_count":{"type":"integer","minimum":0.0,"title":"Market Count","description":"Sum of ticker-level catalog lifetime-overlap market counts in the selected UTC window; not a cross-ticker global condition-id union","examples":[93]},"current_market_count":{"type":"integer","minimum":0.0,"title":"Current Market Count","description":"Sum of ticker-level currently open markets in the latest UTC-day snapshot; use this for live-only market breadth","examples":[64]},"unique_traders":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Unique Traders","description":"Exact service-wide observed participant/proxy-wallet union in the selected period; null when retained wallet-level trades do not fully cover the requested window","examples":[281]},"total_liquidity":{"type":"number","minimum":0.0,"title":"Total Liquidity","description":"Windowed aggregated liquidity signal in USD over the selected period","examples":[245000.0]},"active_tickers":{"type":"integer","minimum":0.0,"title":"Active Tickers","description":"Number of tickers with market activity in the selected period","examples":[31]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Service-wide weighted orderbook-aware implied sentiment score","examples":[0.11]},"positive_count":{"type":"integer","minimum":0.0,"title":"Positive Count","description":"Deprecated. Outcome-aware bullish market count retained for v1 compatibility; prefer bullish_pct with trade_count and market_count for public analysis.","deprecated":true,"examples":[41]},"negative_count":{"type":"integer","minimum":0.0,"title":"Negative Count","description":"Deprecated. Outcome-aware bearish market count retained for v1 compatibility; prefer bearish_pct with trade_count and market_count for public analysis.","deprecated":true,"examples":[29]},"neutral_count":{"type":"integer","minimum":0.0,"title":"Neutral Count","description":"Deprecated. Outcome-aware neutral/unclassified market count retained for v1 compatibility; prefer bullish_pct, bearish_pct, trade_count and market_count for public analysis.","deprecated":true,"examples":[23]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Outcome-aware bullish market percentage","examples":[44]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Outcome-aware bearish market percentage","examples":[31]},"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":[[52.1,54.0,56.8,59.2,61.0,60.1,58.4]]},"drivers":{"items":{"$ref":"#/components/schemas/PolymarketMarketSentimentDriver"},"type":"array","title":"Drivers","description":"Top assets by current buzz_score driving the service-level reading"}},"type":"object","required":["buzz_score","trade_count","market_count","current_market_count","total_liquidity","active_tickers","positive_count","negative_count","neutral_count","bullish_pct","bearish_pct"],"title":"PolymarketMarketSentimentResponse","description":"Service-level Polymarket market sentiment across all tracked stocks.","examples":[{"buzz_score":58.4,"trend":"stable","trade_count":512,"market_count":93,"current_market_count":64,"unique_traders":281,"total_liquidity":245000.0,"active_tickers":31,"sentiment_score":0.11,"positive_count":41,"negative_count":29,"neutral_count":23,"bullish_pct":44,"bearish_pct":31,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,58.4],"drivers":[{"ticker":"AAPL","trade_count":52,"buzz_score":68.9,"sentiment_score":0.28},{"ticker":"TSLA","trade_count":47,"buzz_score":66.3,"sentiment_score":0.19}]}]},"PolymarketPulseEvidence":{"properties":{"directional_coverage":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Directional Coverage","description":"Share of current open snapshot markets with outcome-aware directional evidence"},"traded_market_pct":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Traded Market Pct","description":"Share of current open snapshot markets with trades in the latest UTC day"},"zero_trade_market_pct":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Zero Trade Market Pct","description":"Share of current open snapshot markets without trades in the latest UTC day"},"avg_spread":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Avg Spread","description":"Average YES-token spread across current open snapshot markets with bid/ask spread evidence"},"snapshot_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Snapshot At","description":"Latest stored snapshot timestamp used by the pulse read model"}},"type":"object","title":"PolymarketPulseEvidence","description":"Compact data-quality evidence for the ticker-level Polymarket pulse."},"PolymarketRawMentionItem":{"properties":{"condition_id":{"type":"string","title":"Condition Id","description":"Polymarket condition ID","examples":["0xabc..."]},"event_id":{"type":"string","title":"Event Id","description":"Polymarket event ID","examples":["12345"]},"market_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market Slug","description":"Polymarket market slug","examples":["nvda-up-or-down-on-april-20-2026"]},"question":{"type":"string","title":"Question","description":"Market question/title","examples":["NVDA up or down on April 20?"]},"market_type":{"type":"string","title":"Market Type","description":"Derived market type (`up_down`, `close_above`, `hit_target`, `earnings` or `other`)","examples":["up_down"]},"strike_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Strike Price","description":"Extracted strike price when available","examples":[250.0]},"yes_price":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Yes Price","description":"YES price from this snapshot","examples":[0.63]},"no_price":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"No Price","description":"NO price from this snapshot","examples":[0.37]},"reference_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Reference Price","description":"Stock reference price attached during scrape when needed for range-ladder classification","examples":[101.68]},"reference_price_timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Price Timestamp","description":"Timestamp for `reference_price` when available","examples":["2026-04-20T14:30:00Z"]},"liquidity":{"type":"number","minimum":0.0,"title":"Liquidity","description":"Market liquidity in USD at snapshot time","examples":[7905.52]},"volume_24h":{"type":"number","minimum":0.0,"title":"Volume 24H","description":"Rolling 24h market volume in USD at snapshot time","examples":[2408.43]},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"UTC-day trade count observed for this market snapshot","examples":[42]},"buy_trades":{"type":"integer","minimum":0.0,"title":"Buy Trades","description":"UTC-day Polymarket BUY trades for this snapshot; activity counter, not bullishness","examples":[23]},"sell_trades":{"type":"integer","minimum":0.0,"title":"Sell Trades","description":"UTC-day Polymarket SELL trades for this snapshot; activity counter, not bearishness","examples":[19]},"unique_traders":{"type":"integer","minimum":0.0,"title":"Unique Traders","description":"UTC-day observed participant/proxy-wallet counter for this market snapshot","examples":[31]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Outcome-aware market price sentiment for this snapshot; prefers orderbook midpoint when available, falls back to YES/NO price and is null when direction or evidence is unavailable","examples":[0.26]},"sentiment_label":{"anyOf":[{"type":"string","enum":["positive","negative","neutral"]},{"type":"null"}],"title":"Sentiment Label","description":"Classification derived from `sentiment_score`: positive=bullish, negative=bearish, neutral=flat; null when `sentiment_score` is null","examples":["positive"]},"end_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Date","description":"Market end timestamp when available. Unlike summary `top_mentions`, raw rows preserve the full timestamp from the stored snapshot.","examples":["2026-04-20T23:59:00Z"]},"active":{"type":"boolean","title":"Active","description":"Whether the market is currently open; false for closed or ended markets","examples":[true]},"market_status":{"type":"string","enum":["tradable","open","resolved","inactive","expired"],"title":"Market Status","description":"Compact current market status derived from active, closed, accepting_orders and end_date","examples":["tradable"]},"fetched_at":{"type":"string","format":"date-time","title":"Fetched At","description":"Snapshot fetch timestamp","examples":["2026-04-20T15:00:00Z"]}},"type":"object","required":["condition_id","event_id","question","market_type","liquidity","volume_24h","trade_count","buy_trades","sell_trades","unique_traders","active","market_status","fetched_at"],"title":"PolymarketRawMentionItem","description":"Raw Polymarket market snapshot row for one stock ticker."},"PolymarketRawMentionsResponse":{"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/PolymarketRawMentionItem"},"type":"array","title":"Results","description":"Raw market snapshot rows ordered by newest first"}},"type":"object","required":["ticker","period_days","count","results"],"title":"PolymarketRawMentionsResponse","description":"Paginated raw Polymarket snapshot rows for a single stock ticker.","examples":[{"ticker":"NVDA","period_days":7,"count":1,"results":[{"condition_id":"0xabc...","event_id":"12345","market_slug":"nvda-up-or-down-on-april-20-2026","question":"NVDA up or down on April 20?","market_type":"up_down","strike_price":250.0,"yes_price":0.63,"no_price":0.37,"reference_price":247.82,"reference_price_timestamp":"2026-04-20T14:30:00Z","liquidity":7905.52,"volume_24h":2408.43,"trade_count":42,"buy_trades":23,"sell_trades":19,"unique_traders":31,"sentiment_score":0.26,"sentiment_label":"positive","end_date":"2026-04-20T23:59:00Z","active":true,"market_status":"tradable","fetched_at":"2026-04-20T15:00:00Z"}]}]},"PolymarketSchedulerStatus":{"properties":{"running":{"type":"boolean","title":"Running","description":"Whether worker heartbeat is fresh"},"last_scrape":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Scrape","description":"ISO timestamp of last scrape"},"scrape_count":{"type":"integer","title":"Scrape Count","description":"Total scrape cycles","default":0},"error_count":{"type":"integer","title":"Error Count","description":"Total failed cycles","default":0},"success_rate":{"type":"number","title":"Success Rate","description":"Success ratio","default":0.0},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Additional worker status note"}},"type":"object","required":["running"],"title":"PolymarketSchedulerStatus","description":"Polymarket worker status.","examples":[{"running":true,"last_scrape":"2026-02-18T10:00:00Z","scrape_count":58,"error_count":1,"success_rate":0.983}]},"PolymarketSearchResponse":{"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/PolymarketSearchResultItem"},"type":"array","title":"Results","description":"Top matching stocks capped by the requested limit"}},"type":"object","required":["query","count","period_days","results"],"title":"PolymarketSearchResponse","description":"Search results for Polymarket 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":{"trade_count":14,"buzz_score":71.4,"trend":"rising","sentiment_score":0.34,"bearish_pct":33,"bullish_pct":67,"current_market_count":12,"market_count":27,"total_liquidity":94750.0,"unique_traders":119}}]}]},"PolymarketSearchResultItem":{"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/PolymarketSearchSummary","description":"Last-7-days Polymarket summary for this asset"}},"type":"object","required":["ticker","name","summary"],"title":"PolymarketSearchResultItem","description":"Individual Polymarket search result item."},"PolymarketSearchSummary":{"properties":{"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Trade count in the last 7 UTC calendar days","examples":[14]},"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":[71.4]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price 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":"Orderbook-aware implied sentiment over the last 7 UTC calendar days","examples":[0.34]}},"type":"object","required":["trade_count","buzz_score"],"title":"PolymarketSearchSummary","description":"Compact last-7-days summary attached to Polymarket search results."},"PolymarketStatsResponse":{"properties":{"total_trades":{"type":"integer","minimum":0.0,"title":"Total Trades","description":"Total Polymarket trade activity from daily aggregates"},"total_markets":{"type":"integer","minimum":0.0,"title":"Total Markets","description":"Distinct Polymarket condition_id count"},"unique_tickers":{"type":"integer","minimum":0.0,"title":"Unique Tickers","description":"Distinct tickers with Polymarket market rows in the database"},"open_markets_current":{"type":"integer","minimum":0.0,"title":"Open Markets Current","description":"Currently open Polymarket markets where active=true, closed=false and end_date has not passed","default":0},"open_tickers_current":{"type":"integer","minimum":0.0,"title":"Open Tickers Current","description":"Distinct tickers with at least one currently open Polymarket market","default":0},"traded_markets_today":{"type":"integer","minimum":0.0,"title":"Traded Markets Today","description":"Distinct Polymarket condition_id values with UTC-day trade activity","default":0},"traded_tickers_today":{"type":"integer","minimum":0.0,"title":"Traded Tickers Today","description":"Distinct tickers with UTC-day Polymarket trade activity","default":0},"trades_today":{"type":"integer","minimum":0.0,"title":"Trades Today","description":"Polymarket trade activity during today's UTC date","default":0},"supported_tickers":{"type":"integer","minimum":0.0,"title":"Supported Tickers","description":"Ticker count in ticker_reference"}},"type":"object","required":["total_trades","total_markets","unique_tickers","supported_tickers"],"title":"PolymarketStatsResponse","description":"Polymarket service statistics.","examples":[{"total_trades":15420,"total_markets":713,"unique_tickers":119,"open_markets_current":284,"open_tickers_current":71,"traded_markets_today":39,"traded_tickers_today":17,"trades_today":84,"supported_tickers":11800}]},"PolymarketStockDetailResponse":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["AAPL"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name from ticker_reference","examples":["Apple Inc."]},"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.","deprecated":true},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score (0-100)","examples":[68.9]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["stable"]},"period_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Period Days","description":"Analysis period in days","examples":[7]},"trade_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Trade Count","description":"Trade count in period","examples":[312]},"market_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Market Count","description":"Distinct markets that existed for ticker within the selected UTC window, counted by market-catalog lifetime overlap","examples":[27]},"current_market_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Current Market Count","description":"Number of currently open markets in the latest UTC-day snapshot for ticker; use this for live-only market breadth","examples":[12]},"unique_traders":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Unique Traders","description":"Exact distinct union of observed proxy and explicit maker wallet hashes for the delivered scope and UTC window; null when retained wallet-level trades do not fully cover the window; not a complete market-wide participant census","examples":[119]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Orderbook-aware implied sentiment; null when no directional sentiment evidence exists in the selected period","examples":[0.28]},"positive_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Positive Count","description":"Deprecated. Outcome-aware bullish market count retained for v1 compatibility; prefer bullish_pct with trade_count and market_count for public analysis.","deprecated":true,"examples":[9]},"negative_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Negative Count","description":"Deprecated. Outcome-aware bearish market count retained for v1 compatibility; prefer bearish_pct with trade_count and market_count for public analysis.","deprecated":true,"examples":[5]},"neutral_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Neutral Count","description":"Deprecated. Outcome-aware neutral/unclassified market count retained for v1 compatibility; prefer bullish_pct, bearish_pct, trade_count and market_count for public analysis.","deprecated":true,"examples":[2]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Outcome-aware bullish market percentage","examples":[64]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Outcome-aware bearish market percentage","examples":[36]},"total_liquidity":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Total Liquidity","description":"Windowed aggregated liquidity signal in USD over the selected period; not a current snapshot","examples":[128000.0]},"daily_trend":{"anyOf":[{"items":{"$ref":"#/components/schemas/PolymarketDailyTrendItem"},"type":"array"},{"type":"null"}],"title":"Daily Trend","description":"Daily activity breakdown for the selected period"},"top_mentions":{"anyOf":[{"items":{"$ref":"#/components/schemas/PolymarketTopMention"},"type":"array"},{"type":"null"}],"title":"Top Mentions","description":"Top markets with an active/open snapshot during the retained snapshot portion of the selected UTC-day period for this ticker (including the current UTC day so far), capped at 10 and sorted as representative sentiment evidence: outcome-aware directional markets first, opposing signals kept visible when present, then trade count, with non-open markets de-prioritized and 24h volume and liquidity as tie-breakers. For windows longer than raw snapshot retention, ticker analytics still use `polymarket_daily_stats`, but this representative snapshot list is limited to retained `polymarket_market_snapshots`. Item prices and liquidity come from the selected in-period snapshot, not necessarily the current market state. `active` indicates whether the market is currently open, so historical in-period evidence can now have a non-open current state. `market_status` gives the compact current state."},"pulse":{"anyOf":[{"$ref":"#/components/schemas/PolymarketTickerPulse"},{"type":"null"}],"description":"Compact current Polymarket interpretation built from locally stored latest snapshot evidence. Does not duplicate top-level aggregate fields; concrete market evidence remains in `top_mentions`."}},"type":"object","required":["ticker","found"],"title":"PolymarketStockDetailResponse","description":"Detailed Polymarket data for a single stock.","examples":[{"ticker":"AAPL","company_name":"Apple Inc.","found":true,"buzz_score":68.9,"trend":"stable","period_days":7,"trade_count":312,"market_count":27,"current_market_count":12,"unique_traders":119,"sentiment_score":0.28,"bullish_pct":64,"bearish_pct":36,"total_liquidity":128000.0,"daily_trend":[{"date":"2026-02-13","trade_count":5,"sentiment_score":0.25,"buzz_score":64.1,"bullish_pct":64,"bearish_pct":21}],"top_mentions":[{"condition_id":"0xabc...","question":"Will AAPL close above $220 this week?","market_type":"close_above","trade_count":42,"sentiment_score":0.23,"buzz_score":77.2,"yes_price":0.62,"no_price":0.38,"liquidity":7905.52,"volume_24h":2408.43,"end_date":"2026-02-28","active":true,"market_status":"tradable"}],"pulse":{"mood":"mixed","confidence":60.0,"thin_data":false,"why":["opposing_market_signals","upside_targets_rejected","floor_support"],"warnings":["high_average_spread","low_trade_breadth"],"evidence":{"directional_coverage":1.0,"traded_market_pct":0.231,"zero_trade_market_pct":0.769,"avg_spread":0.099,"snapshot_at":"2026-06-24T06:25:53Z"}}}]},"PolymarketTickerPulse":{"properties":{"mood":{"type":"string","enum":["bullish","bearish","mixed","event_driven","illiquid","unclear"],"title":"Mood","description":"Current compact Polymarket interpretation for this ticker"},"confidence":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Confidence","description":"Interpretation confidence capped by coverage, trade breadth, spread, liquidity and recency"},"thin_data":{"type":"boolean","title":"Thin Data","description":"True when current evidence is insufficient for a strong directional interpretation"},"why":{"items":{"type":"string"},"type":"array","maxItems":4,"minItems":1,"title":"Why","description":"Stable machine-readable reason codes explaining the pulse interpretation"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Stable machine-readable data quality, freshness and tradability warnings"},"evidence":{"$ref":"#/components/schemas/PolymarketPulseEvidence","description":"Compact non-duplicative quality summary for the pulse inputs"}},"type":"object","required":["mood","confidence","thin_data","why","evidence"],"title":"PolymarketTickerPulse","description":"Compact interpretation layer for current ticker-level Polymarket data."},"PolymarketTopMention":{"properties":{"condition_id":{"type":"string","title":"Condition Id","description":"Polymarket condition ID","examples":["0xabc..."]},"question":{"type":"string","title":"Question","description":"Market question/title"},"market_type":{"type":"string","title":"Market Type","description":"Derived market type","examples":["close_above"]},"trade_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Trade Count","description":"UTC-day trade count from the selected in-period snapshot","examples":[42]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Outcome-aware market price sentiment for the selected in-period snapshot; prefers orderbook midpoint when available, falls back to YES/NO price and returns neutral 0.0 when direction is unclassified","examples":[0.23]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Market-level activity buzz score for this selected in-period snapshot","examples":[77.2]},"yes_price":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Yes Price","description":"YES price from the selected in-period snapshot; not necessarily live"},"no_price":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"No Price","description":"NO price from the selected in-period snapshot; not necessarily live"},"liquidity":{"type":"number","minimum":0.0,"title":"Liquidity","description":"Selected in-period snapshot liquidity in USD; not necessarily live","examples":[7905.52]},"volume_24h":{"type":"number","minimum":0.0,"title":"Volume 24H","description":"Selected in-period snapshot rolling 24h volume in USD; not necessarily live","examples":[2408.43]},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date","description":"Market end date (ISO)","examples":["2026-02-28"]},"active":{"type":"boolean","title":"Active","description":"Whether the representative market state is open; snapshot-backed rows use current state, historical daily examples use stored representative state"},"market_status":{"type":"string","enum":["tradable","open","resolved","inactive","expired"],"title":"Market Status","description":"Compact market status for this representative item; snapshot-backed rows use current state, historical daily examples use stored representative state","examples":["tradable"]}},"type":"object","required":["condition_id","question","market_type","sentiment_score","liquidity","volume_24h","active","market_status"],"title":"PolymarketTopMention","description":"Top Polymarket market for a ticker with current open/closed state."},"PolymarketTrendingCountry":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Aggregated activity/flow buzz score using trades, volume, breadth, liquidity and participation"},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)."},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Total trade count in period"},"market_count":{"type":"integer","minimum":0.0,"title":"Market Count","description":"Sum of ticker-level catalog lifetime-overlap market counts in the selected UTC window for this dimension; not a cross-ticker condition-id union"},"current_market_count":{"type":"integer","minimum":0.0,"title":"Current Market Count","description":"Sum of ticker-level currently open markets in the latest UTC-day snapshot; use this for live-only market breadth"},"unique_tickers":{"type":"integer","minimum":0.0,"title":"Unique Tickers","description":"Unique tickers in dimension"},"unique_traders":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Unique Traders","description":"Exact distinct union of observed proxy and explicit maker wallet hashes for the dimension and UTC window; null when retained wallet-level trades do not fully cover the window"},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Weighted implied sentiment; null when no underlying trades exist in the selected period"},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Outcome-aware bullish market percentage"},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Outcome-aware bearish market percentage"},"total_liquidity":{"type":"number","minimum":0.0,"title":"Total Liquidity","description":"Windowed aggregated liquidity signal in USD over the selected period; not a current snapshot"},"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`.","examples":[[48.2,51.0,55.3,61.1,65.8,69.2,72.8]]},"top_tickers":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Top Tickers","description":"Top 5 tickers by trade_count"},"country":{"type":"string","title":"Country","description":"Country name","examples":["United States"]}},"type":"object","required":["buzz_score","trend","trade_count","market_count","current_market_count","unique_tickers","bullish_pct","bearish_pct","total_liquidity","trend_history","top_tickers","country"],"title":"PolymarketTrendingCountry","description":"Trending country on Polymarket.","examples":[{"buzz_score":70.1,"trend":"stable","trade_count":712,"market_count":265,"current_market_count":129,"unique_tickers":10,"unique_traders":402,"sentiment_score":0.18,"bullish_pct":58,"bearish_pct":42,"total_liquidity":472000.0,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,70.1],"top_tickers":["AAPL","TSLA","NVDA","AMZN","GOOGL"],"country":"United States"}]},"PolymarketTrendingSector":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Aggregated activity/flow buzz score using trades, volume, breadth, liquidity and participation"},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)."},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Total trade count in period"},"market_count":{"type":"integer","minimum":0.0,"title":"Market Count","description":"Sum of ticker-level catalog lifetime-overlap market counts in the selected UTC window for this dimension; not a cross-ticker condition-id union"},"current_market_count":{"type":"integer","minimum":0.0,"title":"Current Market Count","description":"Sum of ticker-level currently open markets in the latest UTC-day snapshot; use this for live-only market breadth"},"unique_tickers":{"type":"integer","minimum":0.0,"title":"Unique Tickers","description":"Unique tickers in dimension"},"unique_traders":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Unique Traders","description":"Exact distinct union of observed proxy and explicit maker wallet hashes for the dimension and UTC window; null when retained wallet-level trades do not fully cover the window"},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Weighted implied sentiment; null when no underlying trades exist in the selected period"},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Outcome-aware bullish market percentage"},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Outcome-aware bearish market percentage"},"total_liquidity":{"type":"number","minimum":0.0,"title":"Total Liquidity","description":"Windowed aggregated liquidity signal in USD over the selected period; not a current snapshot"},"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`.","examples":[[48.2,51.0,55.3,61.1,65.8,69.2,72.8]]},"top_tickers":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Top Tickers","description":"Top 5 tickers by trade_count"},"sector":{"type":"string","title":"Sector","description":"Sector name","examples":["Technology"]}},"type":"object","required":["buzz_score","trend","trade_count","market_count","current_market_count","unique_tickers","bullish_pct","bearish_pct","total_liquidity","trend_history","top_tickers","sector"],"title":"PolymarketTrendingSector","description":"Trending sector on Polymarket.","examples":[{"buzz_score":72.8,"trend":"rising","trade_count":312,"market_count":147,"current_market_count":71,"unique_tickers":6,"unique_traders":211,"sentiment_score":0.22,"bullish_pct":61,"bearish_pct":39,"total_liquidity":325000.0,"trend_history":[48.2,51.0,55.3,61.1,65.8,69.2,72.8],"top_tickers":["AAPL","MSFT","NVDA","TSLA","AMD"],"sector":"Technology"}]},"PolymarketTrendingStock":{"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":"Polymarket activity/flow discovery score (0-100); not directional sentiment","examples":[71.4]},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Trade count in selected period","examples":[312]},"market_count":{"type":"integer","minimum":0.0,"title":"Market Count","description":"Distinct markets that existed for ticker within the selected UTC window, counted by market-catalog lifetime overlap","examples":[27]},"current_market_count":{"type":"integer","minimum":0.0,"title":"Current Market Count","description":"Number of currently open markets in the latest UTC-day snapshot for ticker; use this for live-only market breadth","examples":[12]},"unique_traders":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Unique Traders","description":"Exact distinct union of observed proxy and explicit maker wallet hashes for the delivered scope and UTC window; null when retained wallet-level trades do not fully cover the window; not a complete market-wide participant census","examples":[119]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Orderbook-aware implied sentiment (-1 to +1); null when no directional sentiment evidence exists in the selected period","examples":[0.34]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Outcome-aware bullish market percentage","examples":[67]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Outcome-aware bearish market percentage","examples":[33]},"total_liquidity":{"type":"number","minimum":0.0,"title":"Total Liquidity","description":"Windowed aggregated liquidity signal in USD over the selected period; not a current snapshot","examples":[94750.0]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Recent buzz history (oldest→newest). Length follows the resolved period, with a minimum of 7 values. Closed historical windows end at `to`.","examples":[[48.2,51.0,55.3,61.1,65.8,69.2,71.4]]}},"type":"object","required":["ticker","buzz_score","trend","trade_count","market_count","current_market_count","bullish_pct","bearish_pct","total_liquidity"],"title":"PolymarketTrendingStock","description":"Trending stock from Polymarket in Reddit/X-compatible shape.","examples":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":71.4,"trend":"rising","trade_count":312,"market_count":27,"current_market_count":12,"unique_traders":119,"sentiment_score":0.34,"bullish_pct":67,"bearish_pct":33,"total_liquidity":94750.0,"trend_history":[48.2,51.0,55.3,61.1,65.8,69.2,71.4]}]},"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."},"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."},"RedditMarketSentimentDriver":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["SPY"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Attributed mentions in the selected period, including inherited thread-context mentions","examples":[129]},"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":[74.1]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for this asset in the selected period","examples":[0.009]}},"type":"object","required":["ticker","mentions","buzz_score"],"title":"RedditMarketSentimentDriver","description":"Top asset contributing to the service-level Reddit market sentiment."},"RedditMarketSentimentResponse":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Service-wide Reddit heat score relative to the service's trailing 90-day baseline. Around 50 = normal activity, higher values = hotter-than-usual service activity.","examples":[57.4]},"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, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["stable"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Total Reddit mentions across the selected period, including inherited thread-context mentions","examples":[3992]},"unique_posts":{"type":"integer","minimum":0.0,"title":"Unique Posts","description":"Exact distinct Reddit post count across the selected UTC period","examples":[418]},"subreddit_count":{"type":"integer","minimum":0.0,"title":"Subreddit Count","description":"Distinct subreddits contributing in the selected period","examples":[21]},"total_upvotes":{"type":"integer","minimum":0.0,"title":"Total Upvotes","description":"Total upvotes across attributed mentions in the selected period","examples":[15234]},"active_tickers":{"type":"integer","minimum":0.0,"title":"Active Tickers","description":"Number of tickers with qualifying attributed Reddit activity in the selected period","examples":[1000]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Service-wide average sentiment score across all qualifying mentions in the selected period","examples":[0.045]},"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":[1440]},"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":[998]},"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":[1554]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Bullish mention percentage","examples":[36]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Bearish mention percentage","examples":[25]},"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":[[49.8,52.1,50.7,55.6,58.3,60.2,57.4]]},"drivers":{"items":{"$ref":"#/components/schemas/RedditMarketSentimentDriver"},"type":"array","title":"Drivers","description":"Top assets by current buzz_score driving the service-level reading"}},"type":"object","required":["buzz_score","mentions","unique_posts","subreddit_count","total_upvotes","active_tickers","positive_count","negative_count","neutral_count","bullish_pct","bearish_pct"],"title":"RedditMarketSentimentResponse","description":"Service-level Reddit market sentiment across all tracked stocks.","examples":[{"buzz_score":57.4,"trend":"stable","mentions":3992,"unique_posts":418,"subreddit_count":21,"total_upvotes":15234,"active_tickers":1000,"sentiment_score":0.045,"positive_count":1440,"negative_count":998,"neutral_count":1554,"bullish_pct":36,"bearish_pct":25,"trend_history":[49.8,52.1,50.7,55.6,58.3,60.2,57.4],"drivers":[{"ticker":"SPY","mentions":129,"buzz_score":74.1,"sentiment_score":0.009},{"ticker":"GOOGL","mentions":106,"buzz_score":71.8,"sentiment_score":0.029}]}]},"RedditRawMentionItem":{"properties":{"post_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Post Id","description":"Reddit post identifier","examples":["abc123"]},"comment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment Id","description":"Reddit comment identifier when the mention comes from a comment","examples":["def456"]},"subreddit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subreddit","description":"Source subreddit","examples":["wallstreetbets"]},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Public Reddit author name, if scraped","examples":["deepfuckingvalue"]},"text_snippet":{"type":"string","title":"Text Snippet","description":"Stored mention snippet (truncated at ingestion time)","examples":["TSLA looks strong into earnings..."]},"created_utc":{"type":"string","format":"date-time","title":"Created Utc","description":"ISO timestamp of creation","examples":["2026-03-20T18:42:10Z"]},"upvotes":{"type":"integer","title":"Upvotes","description":"Reddit score (upvotes) for this mention row","examples":[381]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Sentiment score (-1 to +1)","examples":[0.62]},"sentiment_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentiment Label","description":"Sentiment label (positive/negative/neutral)","examples":["positive"]},"is_inherited":{"type":"boolean","title":"Is Inherited","description":"Whether ticker context was inherited from the parent thread instead of directly mentioned","examples":[false]}},"type":"object","required":["text_snippet","created_utc","upvotes","is_inherited"],"title":"RedditRawMentionItem","description":"Raw Reddit mention row for one ticker."},"RedditRawMentionsResponse":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"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 for the requested include_inherited filter before limit and offset are applied; only the requested page is returned","examples":[1]},"results":{"items":{"$ref":"#/components/schemas/RedditRawMentionItem"},"type":"array","title":"Results","description":"Raw mention rows ordered by newest first"}},"type":"object","required":["ticker","period_days","count","results"],"title":"RedditRawMentionsResponse","description":"Paginated raw Reddit mentions for a single ticker.","examples":[{"ticker":"TSLA","period_days":7,"count":1,"results":[{"post_id":"abc123","comment_id":"def456","subreddit":"wallstreetbets","author":"user123","text_snippet":"TSLA looks strong into earnings...","created_utc":"2026-03-20T18:42:10Z","upvotes":381,"sentiment_score":0.62,"sentiment_label":"positive","is_inherited":false}]}]},"RedditStatsResponse":{"properties":{"total_mentions":{"type":"integer","title":"Total Mentions","description":"Rollup-backed all-time stock mention total; current-day raw rows may be used only as a bounded freshness fallback","examples":[12833]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers with mentions","examples":[65]},"mentions_today":{"type":"integer","title":"Mentions Today","description":"Stock mention rows created since today's UTC midnight, including posts, comments and inherited thread-context mentions","default":0,"examples":[342]},"unique_tickers_today":{"type":"integer","title":"Unique Tickers Today","description":"Unique tickers (detected using case-sensitive, uppercase-only patterns) including posts, comments and inherited thread-context mentions","default":0,"examples":[21]},"supported_tickers":{"type":"integer","title":"Supported Tickers","description":"Number of supported ticker patterns (from ticker_reference)","examples":[11800]}},"type":"object","required":["total_mentions","unique_tickers","supported_tickers"],"title":"RedditStatsResponse","description":"Service statistics.","examples":[{"total_mentions":12833,"unique_tickers":65,"mentions_today":342,"unique_tickers_today":21,"supported_tickers":11800}]},"RootHealthResponse":{"properties":{"status":{"type":"string","enum":["healthy","unhealthy"],"title":"Status","description":"Aggregated root health status","examples":["healthy"]},"service":{"type":"string","title":"Service","description":"Root service identifier","default":"adanos-api"},"version":{"type":"string","title":"Version","description":"Service version","examples":["1.49.0"]},"summary":{"$ref":"#/components/schemas/RootHealthSummary","description":"Aggregated health counts"},"services":{"additionalProperties":{"additionalProperties":true,"type":"object"},"type":"object","title":"Services","description":"Per-platform health payloads keyed by service identifier"}},"type":"object","required":["status","version","summary","services"],"title":"RootHealthResponse","description":"Root API health status aggregated across platforms.","examples":[{"status":"healthy","service":"adanos-api","version":"1.49.0","summary":{"total":5,"healthy":5,"unhealthy":0,"unhealthy_services":[]},"services":{"news-stocks":{"service":"news-stocks","status":"healthy","version":"1.49.0"},"polymarket-stocks":{"service":"polymarket-stocks","status":"healthy","version":"1.49.0"},"reddit-crypto":{"service":"reddit-crypto","status":"healthy","version":"1.49.0"},"reddit-stocks":{"service":"reddit-stocks","status":"healthy","version":"1.49.0"},"x-stocks":{"service":"x-stocks","status":"healthy","version":"1.49.0"}}}]},"RootHealthSummary":{"properties":{"total":{"type":"integer","title":"Total","description":"Number of platform health checks"},"healthy":{"type":"integer","title":"Healthy","description":"Number of checks that reported healthy"},"unhealthy":{"type":"integer","title":"Unhealthy","description":"Number of checks that reported unhealthy or timed out"},"unhealthy_services":{"items":{"type":"string"},"type":"array","title":"Unhealthy Services","description":"Service identifiers that reported unhealthy or timed out"}},"type":"object","required":["total","healthy","unhealthy","unhealthy_services"],"title":"RootHealthSummary","description":"Aggregated root health summary."},"SchedulerStatus":{"properties":{"running":{"type":"boolean","title":"Running","description":"Whether worker is alive (based on heartbeat freshness)"},"last_scrape":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Scrape","description":"ISO timestamp of last scrape (null if never run)"},"scrape_count":{"type":"integer","title":"Scrape Count","description":"Total number of scrapes performed","default":0},"error_count":{"type":"integer","title":"Error Count","description":"Total number of scrape errors/failures","default":0},"success_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Success Rate","description":"Scrape success rate (0.0-1.0)"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Additional info (e.g., worker heartbeat status)"}},"type":"object","required":["running"],"title":"SchedulerStatus","description":"Scheduler status information.","examples":[{"running":true,"last_scrape":"2026-01-09T10:30:00Z","scrape_count":142,"error_count":3,"success_rate":0.979}]},"SearchResponse":{"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/SearchResultItem"},"type":"array","title":"Results","description":"Top matching stocks capped by the requested limit"}},"type":"object","required":["query","count","period_days","results"],"title":"SearchResponse","description":"Search results for 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":342,"buzz_score":87.5,"trend":"rising","sentiment_score":0.23,"bearish_pct":18,"bullish_pct":45,"subreddit_count":8,"total_upvotes":15234,"unique_posts":45}}]}]},"SearchResultItem":{"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 (NYSE, NASDAQ, etc.)","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/StockSearchSummary","description":"Last-7-days Reddit summary for this asset"}},"type":"object","required":["ticker","name","summary"],"title":"SearchResultItem","description":"Individual search result item."},"SentimentAnalyzeRequest":{"properties":{"text":{"type":"string","maxLength":2048,"minLength":1,"title":"Text","description":"Financial or trading text to analyze.","examples":["TSLA looks like a short squeeze setup, loading calls"]}},"type":"object","required":["text"],"title":"SentimentAnalyzeRequest","description":"Direct text sentiment analysis request.","examples":[{"text":"TSLA looks like a short squeeze setup, loading calls"}]},"SentimentAnalyzeResponse":{"properties":{"text":{"type":"string","title":"Text","description":"Normalized input text that was analyzed"},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"-1.0 bearish to +1.0 bullish","examples":[0.78]},"sentiment_label":{"type":"string","enum":["positive","neutral","negative"],"title":"Sentiment Label","description":"Adanos three-class sentiment label, matching top_mentions payloads","examples":["positive"]},"components":{"$ref":"#/components/schemas/SentimentComponents","description":"Whitelisted finance sentiment engine components"}},"type":"object","required":["text","sentiment_score","sentiment_label","components"],"title":"SentimentAnalyzeResponse","description":"Direct text sentiment analysis response.","examples":[{"text":"TSLA looks like a short squeeze setup, loading calls","sentiment_score":0.78,"sentiment_label":"positive","components":{"engine_version":"5.4","vader_compound":0.34,"roberta_score":0.61,"emoji_score":0.0,"phrase_adjustment":0.21,"phrase_matches":[{"phrase":"short squeeze","score":3.5}],"contextual_finance_matches":[]}}]},"SentimentComponents":{"properties":{"engine_version":{"type":"string","title":"Engine Version","description":"Sentiment engine version","examples":["5.4"]},"vader_compound":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Vader Compound","description":"VADER compound score after finance lexicon tuning","examples":[0.34]},"roberta_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Roberta Score","description":"RoBERTa ONNX sentiment score when ensemble inference runs","examples":[0.61]},"emoji_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Emoji Score","description":"Emoji-derived sentiment score","examples":[0.6]},"phrase_adjustment":{"type":"number","title":"Phrase Adjustment","description":"Directional finance phrase adjustment","examples":[0.21]},"phrase_matches":{"items":{"$ref":"#/components/schemas/SentimentPhraseMatch"},"type":"array","title":"Phrase Matches","description":"Directional finance phrases matched by the engine"},"contextual_finance_matches":{"items":{"type":"string"},"type":"array","title":"Contextual Finance Matches","description":"Contextual finance phrases that dampened or informed scoring","examples":[["covered calls"]]}},"type":"object","required":["engine_version","emoji_score","phrase_adjustment"],"title":"SentimentComponents","description":"Whitelisted sentiment engine components exposed publicly."},"SentimentPhraseMatch":{"properties":{"phrase":{"type":"string","title":"Phrase","description":"Matched finance phrase","examples":["short squeeze"]},"score":{"type":"number","title":"Score","description":"Internal phrase sentiment score","examples":[3.5]}},"type":"object","required":["phrase","score"],"title":"SentimentPhraseMatch","description":"Whitelisted directional finance phrase metadata."},"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"}]},"StockSearchSummary":{"properties":{"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Attributed mentions in the last 7 UTC calendar days, including inherited thread-context mentions","examples":[342]},"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":[87.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, upvotes and subreddit breadth; not price 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.23]}},"type":"object","required":["mentions","buzz_score"],"title":"StockSearchSummary","description":"Compact last-7-days summary attached to stock search results."},"StockSentiment":{"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 (null if not found)","examples":["Tesla, Inc."]},"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.","deprecated":true},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz Score (0-100). Asymptotic scaling above 50.","examples":[87.5]},"mentions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentions","description":"Total attributed mentions in the selected period, including inherited thread-context mentions","examples":[342]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score (-1 bearish to +1 bullish)","examples":[0.23]},"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,"examples":[154]},"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,"examples":[62]},"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,"examples":[126]},"total_upvotes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Upvotes","description":"Total upvotes across attributed mentions","examples":[15234]},"unique_posts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Unique Posts","description":"Number of unique posts","examples":[45]},"subreddit_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Subreddit Count","description":"Number of subreddits with mentions","examples":[8]},"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, upvotes and subreddit breadth; not price 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 mentions","examples":[45]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[18]},"period_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Period Days","description":"Analysis period in days","examples":[7]},"top_subreddits":{"anyOf":[{"items":{"$ref":"#/components/schemas/SubredditCount"},"type":"array"},{"type":"null"}],"title":"Top Subreddits","description":"Top subreddits by attributed mention count"},"daily_trend":{"anyOf":[{"items":{"$ref":"#/components/schemas/DailyTrendItem"},"type":"array"},{"type":"null"}],"title":"Daily Trend","description":"Daily attributed mention breakdown for the selected period, with sentiment and buzz_score"},"top_mentions":{"anyOf":[{"items":{"$ref":"#/components/schemas/TopMention"},"type":"array"},{"type":"null"}],"title":"Top Mentions","description":"Top explicit mentions from the selected period, ranked by upvotes"}},"type":"object","required":["ticker","found"],"title":"StockSentiment","description":"Detailed sentiment analysis for a specific stock ticker.","examples":[{"ticker":"TSLA","company_name":"Tesla, Inc.","found":true,"buzz_score":87.5,"mentions":342,"sentiment_score":0.23,"total_upvotes":15234,"unique_posts":45,"subreddit_count":8,"trend":"rising","bullish_pct":45,"bearish_pct":18,"period_days":7,"top_subreddits":[{"subreddit":"wallstreetbets","mentions":89,"count":89},{"subreddit":"stocks","mentions":67,"count":67}],"daily_trend":[{"date":"2025-12-28","mentions":52,"sentiment_score":0.31,"buzz_score":42.8,"bullish_pct":58,"bearish_pct":19},{"date":"2025-12-27","mentions":48,"sentiment_score":0.18,"buzz_score":38.5,"bullish_pct":46,"bearish_pct":21}],"top_mentions":[{"text_snippet":"TSLA looking strong after...","sentiment_score":0.85,"sentiment_label":"positive","upvotes":1234,"subreddit":"wallstreetbets","created_utc":"2025-12-28T10:30:00"}]}]},"SubredditCount":{"properties":{"subreddit":{"type":"string","title":"Subreddit","description":"Subreddit name","examples":["wallstreetbets"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Attributed mentions in this subreddit","examples":[89]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for this subreddit in the selected period","examples":[0.31]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Contributor-level buzz score for this subreddit in the selected period","examples":[64.2]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Deprecated alias for mentions. Use mentions instead.","deprecated":true,"examples":[89]}},"type":"object","required":["subreddit","mentions","count"],"title":"SubredditCount","description":"Subreddit contributor metrics for a stock detail response."},"TopMention":{"properties":{"text_snippet":{"type":"string","title":"Text Snippet","description":"Clean Reddit paragraph around the detected ticker mention (up to 500 chars)","examples":["TSLA looking strong after..."]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Sentiment score (-1 to +1)","examples":[0.85]},"sentiment_label":{"type":"string","title":"Sentiment Label","description":"Sentiment label (positive/negative/neutral)","examples":["positive"]},"upvotes":{"type":"integer","title":"Upvotes","description":"Number of upvotes","examples":[1234]},"subreddit":{"type":"string","title":"Subreddit","description":"Source subreddit","examples":["wallstreetbets"]},"created_utc":{"type":"string","format":"date-time","title":"Created Utc","description":"ISO timestamp of creation","examples":["2025-12-28T10:30:00"]}},"type":"object","required":["text_snippet","sentiment_score","sentiment_label","upvotes","subreddit","created_utc"],"title":"TopMention","description":"Top mention by upvotes."},"TrendingCountry":{"properties":{"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Aggregated Buzz Score (0-100)","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, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total attributed mentions, including inherited thread-context mentions","examples":[4523]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers mentioned","examples":[34]},"subreddit_count":{"type":"integer","title":"Subreddit Count","description":"Number of subreddits with mentions","examples":[15]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Weighted average sentiment (-1 bearish to +1 bullish)","examples":[0.28]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Percentage of sentiment-labeled mentions that are bullish","examples":[54]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Percentage of sentiment-labeled mentions that are bearish","examples":[22]},"total_upvotes":{"type":"integer","title":"Total Upvotes","description":"Total upvotes across attributed 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`.","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 mentions","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","subreddit_count","sentiment_score","bullish_pct","bearish_pct","total_upvotes","trend_history","top_tickers","country"],"title":"TrendingCountry","description":"Trending country with aggregated buzz metrics from Reddit.","examples":[{"buzz_score":82.3,"trend":"stable","mentions":8934,"unique_tickers":156,"subreddit_count":18,"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"}]},"TrendingSector":{"properties":{"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Aggregated Buzz Score (0-100)","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, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total attributed mentions, including inherited thread-context mentions","examples":[4523]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers mentioned","examples":[34]},"subreddit_count":{"type":"integer","title":"Subreddit Count","description":"Number of subreddits with mentions","examples":[15]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Weighted average sentiment (-1 bearish to +1 bullish)","examples":[0.28]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Percentage of sentiment-labeled mentions that are bullish","examples":[54]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Percentage of sentiment-labeled mentions that are bearish","examples":[22]},"total_upvotes":{"type":"integer","title":"Total Upvotes","description":"Total upvotes across attributed 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`.","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 mentions","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","subreddit_count","sentiment_score","bullish_pct","bearish_pct","total_upvotes","trend_history","top_tickers","sector"],"title":"TrendingSector","description":"Trending sector with aggregated buzz metrics from Reddit.","examples":[{"buzz_score":78.4,"trend":"rising","mentions":4523,"unique_tickers":34,"subreddit_count":15,"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"}]},"TrendingStock":{"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 (null if not found)","examples":["Tesla, Inc."]},"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Buzz Score (0-100). Asymptotic scaling above 50.","examples":[87.5]},"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, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total attributed mentions, including inherited thread-context mentions","examples":[342]},"unique_posts":{"type":"integer","title":"Unique Posts","description":"Number of unique posts","examples":[45]},"subreddit_count":{"type":"integer","title":"Subreddit Count","description":"Number of subreddits with mentions","examples":[8]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Average sentiment score (-1 bearish to +1 bullish)","examples":[0.23]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[45]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[18]},"total_upvotes":{"type":"integer","title":"Total Upvotes","description":"Total upvotes across attributed mentions","examples":[15234]},"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. Values 0-100.","examples":[[12.3,15.2,18.7,22.1,28.5,35.2,42.8]]}},"type":"object","required":["ticker","buzz_score","trend","mentions","unique_posts","subreddit_count","sentiment_score","bullish_pct","bearish_pct","total_upvotes"],"title":"TrendingStock","description":"Trending stock with buzz metrics from Reddit.","examples":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"unique_posts":45,"subreddit_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"total_upvotes":15234,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]}]},"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."},"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."},"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"}]},"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]}]}]},"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."},"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."},"XHealthResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Current health status (healthy/unhealthy)","examples":["healthy"]},"service":{"type":"string","title":"Service","description":"Service identifier","examples":["x-stocks"]},"version":{"type":"string","title":"Version","description":"Current API version","examples":["1.49.0"]},"total_mentions":{"type":"integer","title":"Total Mentions","description":"Mentions observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable.","examples":[15420]},"tickers_tracked":{"type":"integer","title":"Tickers Tracked","description":"Distinct tickers observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable.","examples":[247]},"scheduler":{"anyOf":[{"$ref":"#/components/schemas/XSchedulerStatus"},{"type":"null"}],"description":"X Worker status (from worker_heartbeat table)"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if unhealthy"}},"type":"object","required":["status","service","version","total_mentions","tickers_tracked"],"title":"XHealthResponse","description":"X/Twitter service health status - aligned with Reddit health response.","examples":[{"status":"healthy","service":"x-stocks","version":"1.49.0","total_mentions":15420,"tickers_tracked":247,"scheduler":{"running":true,"last_scrape":"2025-12-31T06:00:00Z","scrape_count":42,"error_count":2,"success_rate":0.95}}]},"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."},"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}]}]},"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."},"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"}]}]},"XSchedulerStatus":{"properties":{"running":{"type":"boolean","title":"Running","description":"Whether worker is alive (heartbeat < 90 min old)","examples":[true]},"last_scrape":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Scrape","description":"ISO timestamp of last completed scrape cycle"},"scrape_count":{"type":"integer","title":"Scrape Count","description":"Total completed scrape cycles since worker start","default":0},"error_count":{"type":"integer","title":"Error Count","description":"Total failed scrape cycles","default":0},"success_rate":{"type":"number","title":"Success Rate","description":"Success rate (success_count / scrape_count)","default":0.0,"examples":[0.95]},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Additional status info (e.g., worker crash warning)"}},"type":"object","required":["running"],"title":"XSchedulerStatus","description":"X Worker scheduler/scraper status (from worker_heartbeat table).","examples":[{"running":true,"last_scrape":"2025-12-31T06:00:00Z","scrape_count":42,"error_count":2,"success_rate":0.95}]},"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}}]}]},"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."},"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":11800}]},"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.\n\nV5.5: Uses real tweet data from x_mentions table with HHI-based effective\nauthor 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}]}]},"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."},"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"}]},"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"}]},"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"}]},"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.\n\nV5.5: Uses real tweet data from x_mentions (collected via twscrape).\nAuthor diversity now prefers HHI-based effective authors from\nauthor_distribution and falls back to scaled unique_authors only when the\nfull 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]}]}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","description":"API key for authentication.\n\nGet your API key at https://adanos.org/register.\n\nFormat: `sk_live_` followed by 32 hexadecimal characters.","in":"header","name":"X-API-Key"}}},"tags":[{"name":"Reddit Stocks","description":"Retail stock discussion data from Reddit. Start with `/trending`, then drill into `/stock/{ticker}` or build watchlists with `/compare`."},{"name":"Reddit Crypto","description":"Crypto sentiment on Reddit with the same discovery/search/compare pattern as the stock APIs."},{"name":"X/Twitter Stocks","description":"Fast-moving stock attention from X/Twitter cashtags and tweet engagement, useful for momentum discovery and validation."},{"name":"Polymarket Stocks","description":"Prediction-market based stock sentiment and attention from Polymarket prices, trades, liquidity and orderbook signals. Metrics are market-centric rather than mention-based."},{"name":"News Stocks","description":"Editorial/news sentiment with source breadth. Use `source` on supported endpoints to isolate a publisher or canonical source id."},{"name":"Health-Check","description":"Operational health and freshness checks. Useful for monitoring, not required for normal client integrations."},{"name":"Finance Sentiment","description":"Direct finance-tuned sentiment analysis for client-provided trading, market and investment text."}]}