openapi: 3.1.0
info:
  title: Adanos Market Sentiment API
  description: "\nThe Adanos API measures how much attention stocks and crypto tokens\
    \ get on **Reddit**, **X/Twitter**, **financial news** and **Polymarket**. It\
    \ shows whether that attention is bullish or bearish. A separate endpoint scores\
    \ the sentiment of financial text you send. Reference coverage is 35,000+ stock\
    \ tickers.\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\n## Quickstart\n\n1. Create a free API key at [adanos.org/register](https://adanos.org/register).\
    \ Store it in `ADANOS_API_KEY`, not in browser code or public repositories.\n\
    2. Send it in the `X-API-Key` header. This call returns the three stocks with\
    \ the most Reddit attention today (response shortened):\n\n```bash\ncurl \"https://api.adanos.org/reddit/stocks/v1/trending?limit=3\"\
    \ \\\n  -H \"X-API-Key: $ADANOS_API_KEY\"\n```\n\n```json\n[\n  {\n    \"ticker\"\
    : \"TSLA\",\n    \"company_name\": \"Tesla, Inc.\",\n    \"buzz_score\": 87.5,\n\
    \    \"trend\": \"rising\",\n    \"sentiment_score\": 0.23\n  }\n]\n```\n\n##\
    \ Platforms\n\n| Platform | Base path |\n|----------|-----------|\n| Reddit Stocks\
    \ | `/reddit/stocks/v1` |\n| X/Twitter Stocks | `/x/stocks/v1` |\n| News Stocks\
    \ | `/news/stocks/v1` |\n| Polymarket Stocks | `/polymarket/stocks/v1` |\n| Reddit\
    \ Crypto | `/reddit/crypto/v1` |\n| Finance Sentiment | `/sentiment/v1` |\n\n\
    Each stock platform offers `/trending`, `/stock/{ticker}`, `/compare` and `/search`.\n\
    \n## Key metrics\n\n| Field | Meaning |\n|-------|---------|\n| `buzz_score` |\
    \ Attention on one platform, from 0 to 100 |\n| `sentiment_score` | From `-1.0`\
    \ (bearish) to `+1.0` (bullish). `null` when too few mentions take a side. |\n\
    | `bullish_pct`, `bearish_pct` | Share of directional mentions that are bullish\
    \ or bearish, in percent |\n| `trend` | `rising`, `falling` or `stable`. Compares\
    \ activity in the last 3 days with the 3 days before; the share price plays no\
    \ part. |\n\nA `null` value means the field has no data for this asset and period.\n\
    \n## Limits and errors\n\n- Free keys allow 250 requests per month, 100 per minute\
    \ and 30 days of history. The `X-RateLimit-*` headers show what is left.\n- After\
    \ a `429`, wait the number of seconds in `Retry-After`. The monthly quota resets\
    \ at `X-RateLimit-Reset-Monthly`.\n- Errors return JSON with a `detail` field.\
    \ It holds a message, a list of invalid fields or an object with a `message`.\n\
    - Responses carry an `X-Request-ID` header. Include it when you contact [support@adanos.org](mailto:support@adanos.org).\n\
    \n## Notes\n\n- Set the period with `from` and `to` (UTC dates, `YYYY-MM-DD`).\
    \ Without them, `/trending` and `/market-sentiment` show the current day. `/stock/{ticker}`\
    \ and `/compare` show the last 7 days.\n- For AI agents, [`/llms.txt`](/llms.txt)\
    \ describes the whole API in plain text.\n\n"
  termsOfService: https://adanos.org/terms
  contact:
    name: API Support
    url: https://api.adanos.org/
    email: support@adanos.org
  license:
    name: MIT (OpenAPI document only)
    url: https://opensource.org/licenses/MIT
  version: 1.53.4
servers:
- url: https://api.adanos.org
  description: Production
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`.


        **Includes:**

        - `buzz_score`: normalized 0-100 activity score used for ranking

        - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions, upvotes and subreddit breadth; not price movement. For
        `from`/`to`, anchors at `to` (or now when `to` is today)

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals

        - `mentions`, `unique_posts`, `subreddit_count`, `total_upvotes`: attributed
        volume and engagement signals, including inherited thread-context mentions

        - `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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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`.


        **Includes:**

        - `buzz_score`: normalized 0-100 activity score used for ranking

        - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions, upvotes and subreddit breadth; not price movement. For
        `from`/`to`, anchors at `to` (or now when `to` is today)

        - `mentions`, `unique_tickers`, `subreddit_count`, `total_upvotes`: attributed
        volume and engagement signals, including inherited thread-context mentions

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals

        - `top_tickers`: up to 5 tickers driving the sector result

        - `trend_history`: independent daily sector buzz scores, oldest to newest;
        length is max(requested days, 7); the live final value describes today so
        far and can differ from period `buzz_score`'
      operationId: 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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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`.


        **Includes:**

        - `buzz_score`: normalized 0-100 activity score used for ranking

        - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions, upvotes and subreddit breadth; not price movement. For
        `from`/`to`, anchors at `to` (or now when `to` is today)

        - `mentions`, `unique_tickers`, `subreddit_count`, `total_upvotes`: attributed
        volume and engagement signals, including inherited thread-context mentions

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals

        - `top_tickers`: up to 5 tickers driving the country result

        - `trend_history`: independent daily country buzz scores, oldest to newest;
        length is max(requested days, 7); the live final value describes today so
        far and can differ from period `buzz_score`'
      operationId: 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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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 the Reddit report for one stock ticker.


        **Includes:**

        - `buzz_score`: normalized Reddit activity score for the selected period

        - `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)

        - `sentiment_score`, `bullish_pct`, `bearish_pct`, `positive_count`, `negative_count`,
        `neutral_count`: directional sentiment signals

        - `mentions`, `unique_posts`, `subreddit_count`, `total_upvotes`: attributed
        volume and engagement signals, including inherited thread-context mentions

        - `daily_trend`: daily Reddit activity and sentiment values

        - `top_mentions`: top explicit Reddit mentions from the selected period, ranked
        by upvotes

        - `top_subreddits`: top subreddit contributors by attributed mention count


        Use raw `/mentions` without `include_inherited` for explicit-only rows.


        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: 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.
      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: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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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 one reading for all Reddit stock discussion: overall buzz,
        sentiment split, activity trend, breadth and the `drivers` behind it, ranked
        by `buzz_score`.


        Here `buzz_score` compares overall Reddit stock activity with its own trailing
        90-day baseline:

        - around `50` = normal Reddit market activity

        - higher = more active than usual

        - lower = quieter than usual


        `trend` is activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions, upvotes and subreddit breadth; not price movement. For
        `from`/`to`, anchors at `to` (or now when `to` is today).


        Use `sentiment_score`, `bullish_pct` and `bearish_pct` for direction.


        `mentions` includes inherited thread-context mentions. Use raw `/mentions`
        without

        `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.
      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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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.


        **Includes:**

        - `explanation`: 1-2 sentence summary of why the stock is trending

        - `cached`: whether this was served from cache

        - `generated_at`: when the explanation was generated

        - `model`: the language model that wrote 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: google/gemma-4-31B-it-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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport requests\n\nresponse = requests.get(\n    \"\
          https://api.adanos.org/reddit/stocks/v1/stock/TSLA/explain\",\n    headers={\n\
          \        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\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.


        Results are sorted by `buzz_score` descending and return the same core analytics
        used by

        `/trending`: `buzz_score`, `trend`, `trend_history`, `mentions`, `unique_posts`,

        `subreddit_count`, `sentiment_score`, `bullish_pct`, `bearish_pct` and `total_upvotes`.

        `trend` is activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions, upvotes and subreddit breadth; not price movement. For
        `from`/`to`, anchors at `to` (or now when `to` is today).


        Each requested ticker gets one row. Tickers without activity in the period,
        including unsupported ones, return zeroed metrics. Unsupported tickers have
        no company name; use `/search` to check support.


        `mentions` includes inherited thread-context mentions. Use raw `/mentions`
        without

        `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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport requests\n\nresponse = requests.get(\n    \"\
          https://api.adanos.org/reddit/stocks/v1/search?q=tesla&limit=5\",\n    headers={\n\
          \        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n\
          )\nresponse.raise_for_status()\nprint(response.json())"
  /reddit/stocks/v1/stats:
    get:
      tags:
      - Reddit Stocks
      summary: Dataset statistics
      description: 'Returns high-level Reddit stock dataset coverage metrics for questions
        like:

        - how many stock mention rows are stored

        - how many distinct tickers currently have Reddit data

        - how many mention rows and distinct tickers are present today (UTC)

        - how many supported tickers exist in the reference universe


        Today''s counters start at 00:00 UTC and include post, comment 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: 35000
          headers:
            X-Request-ID:
              description: Request correlation identifier returned by the API and
                included in structured application logs.
              schema:
                type: string
              example: adnos.req-20260423.abc12345
            Cache-Control:
              description: HTTP cache policy returned by the API.
              schema:
                type: string
              example: private, max-age=300
            Vary:
              description: Headers that private client caches must include in their
                cache key.
              schema:
                type: string
              example: X-API-Key, Authorization, Accept-Encoding
            X-RateLimit-Limit-Monthly:
              description: Monthly request quota for the authenticated account.
              schema:
                type: string
              example: '250'
            X-RateLimit-Remaining-Monthly:
              description: Remaining monthly requests for the authenticated account.
              schema:
                type: string
              example: '247'
            X-RateLimit-Used-Monthly:
              description: Requests already consumed in the account's current monthly
                quota window.
              schema:
                type: string
              example: '3'
            X-RateLimit-Reset-Monthly:
              description: ISO 8601 timestamp when the current monthly quota window
                resets.
              schema:
                type: string
                format: date-time
              example: '2026-07-29T14:03:00Z'
            X-RateLimit-Limit-Burst:
              description: Per-minute burst request quota for the authenticated account.
              schema:
                type: string
              example: '100'
            X-RateLimit-Remaining-Burst:
              description: Remaining requests in the current per-minute burst window.
              schema:
                type: string
              example: '99'
            X-RateLimit-Reset-Burst:
              description: ISO 8601 timestamp when the current burst rate-limit window
                resets.
              schema:
                type: string
                format: date-time
              example: '2026-04-28T14:30:00Z'
            X-Account-Type:
              description: Account tier resolved from the API key.
              schema:
                type: string
                enum:
                - free
                - hobby
                - professional
                - premium
              example: free
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing:
                  summary: Missing API key
                  value:
                    detail: Missing API key. Include 'X-API-Key' header.
                invalid:
                  summary: Invalid API key
                  value:
                    detail: Invalid API key.
                revoked:
                  summary: Revoked API key
                  value:
                    detail: API key has been revoked.
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
              examples:
                burst:
                  summary: Fleet burst limit exceeded
                  value:
                    detail:
                      error: Burst rate limit exceeded
                      message: Too many requests. Limit is 100 requests per minute.
                      limit: 100
                      used: 100
                      account_type: free
                local:
                  summary: Local backup limiter exceeded
                  value:
                    detail:
                      error: Rate limit exceeded
                      message: 'Rate limit exceeded: 100 per 1 minute'
                      limit: 100
                      account_type: free
        '503':
          description: Database temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Database temporarily unavailable
        '504':
          description: Analytics request deadline exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Request deadline exceeded
      security:
      - ApiKeyAuth: []
      x-codeSamples:
      - lang: curl
        label: cURL
        source: "curl \"https://api.adanos.org/reddit/stocks/v1/stats\" \\\n  -H \"\
          X-API-Key: $ADANOS_API_KEY\""
      - lang: javascript
        label: JavaScript
        source: "const response = await fetch(\"https://api.adanos.org/reddit/stocks/v1/stats\"\
          , {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\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 os\n\nimport requests\n\nresponse = requests.get(\n    \"\
          https://api.adanos.org/reddit/stocks/v1/stats\",\n    headers={\n      \
          \  \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\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.

        **Professional account required.** Free and Hobby accounts cannot use this
        endpoint.


        **Use this endpoint when you need:**

        - post/comment-level snippets

        - original timestamps

        - inherited-context filtering


        **Notes:**

        - Use `from` and `to` for explicit UTC date windows

        - Results are ordered newest first and support deterministic `offset` + `limit`
        pagination

        - `include_inherited=false` by default

        - 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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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`.


        **Includes:**

        - `buzz_score`: normalized 0-100 activity score used for ranking

        - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions, upvotes and subreddit breadth; not price movement. For
        `from`/`to`, anchors at `to` (or now when `to` is today)

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals

        - `mentions`, `unique_posts`, `subreddit_count`, `total_upvotes`: attributed
        volume and engagement signals, including inherited thread-context mentions

        - `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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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 Reddit report for one crypto symbol.


        **Includes:**

        - `buzz_score`: normalized Reddit activity score for the selected period

        - `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)

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals

        - `mentions`, `unique_posts`, `subreddit_count`, `total_upvotes`: attributed
        volume and engagement signals, including inherited thread-context mentions

        - `daily_trend`: daily Reddit activity and sentiment values

        - `top_mentions`: representative high-engagement Reddit posts or comments
        from the selected period


        Returns `200` with `found: false` when the symbol is supported but this service

        has no qualifying data in the requested window. Returns `404` only when the

        symbol 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.
      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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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 one reading for all Reddit crypto discussion: overall
        buzz, sentiment split, activity trend, breadth and the `drivers` behind it,
        ranked by `buzz_score`.


        Here `buzz_score` compares overall Reddit crypto discussion with its own trailing
        90-day baseline:

        - around `50` = normal Reddit crypto activity

        - higher = more active than usual

        - lower = quieter than usual


        `trend` is activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions, upvotes and subreddit breadth; not price movement. For
        `from`/`to`, anchors at `to` (or now when `to` is today).


        Use `sentiment_score`, `bullish_pct` and `bearish_pct` for direction.


        `mentions` includes inherited thread-context mentions. Use raw `/mentions`
        without

        `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.
      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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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.


        Use it for watchlists: one compact row per symbol.

        Results 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`.

        `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).

        Each requested symbol gets one row. Symbols without activity in the period,
        including unsupported ones, return zeroed metrics. Unsupported symbols have
        no name; use `/search` to check support.'
      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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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.

        Summary `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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport requests\n\nresponse = requests.get(\n    \"\
          https://api.adanos.org/reddit/crypto/v1/search?q=bitcoin&limit=5\",\n  \
          \  headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n \
          \   },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"
  /reddit/crypto/v1/stats:
    get:
      tags:
      - Reddit Crypto
      summary: Dataset statistics
      description: 'Returns high-level Reddit Crypto dataset coverage metrics.


        Includes:

        - total mention rows stored

        - number of distinct tracked symbols with data, exposed as `unique_tokens`

        - today''s UTC mention and distinct symbol counts, exposed as `unique_tokens_today`

        - number of supported symbols, 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: $ADANOS_API_KEY\""
      - lang: javascript
        label: JavaScript
        source: "const response = await fetch(\"https://api.adanos.org/reddit/crypto/v1/stats\"\
          , {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\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 os\n\nimport requests\n\nresponse = requests.get(\n    \"\
          https://api.adanos.org/reddit/crypto/v1/stats\",\n    headers={\n      \
          \  \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\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.

        **Professional account required.** Free and Hobby accounts cannot use this
        endpoint.


        **Use this endpoint when you need:**

        - post/comment-level snippets

        - original timestamps

        - inherited-context filtering


        **Notes:**

        - Use `from` and `to` for explicit UTC date windows

        - Results are ordered newest first and support deterministic `offset` + `limit`
        pagination

        - `include_inherited=false` by default

        - 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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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`.


        **Includes:**

        - `buzz_score`: normalized 0-100 activity score used for ranking

        - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions, likes and author breadth; not price movement. For `from`/`to`,
        anchors at `to` (or now when `to` is today)

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals

        - `mentions`, `unique_tweets`, `total_upvotes`: volume and engagement signals

        - `trend_history`: independent UTC-day buzz scores, oldest to newest; minimum
        7 values; the live final value describes today so far and can differ from
        the selected-period `buzz_score`; missing days are `0.0`'
      operationId: getXTrendingStocks
      security:
      - ApiKeyAuth: []
      parameters:
      - name: from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: Start date in YYYY-MM-DD. Inclusive UTC date.
          title: From
        description: Start date in YYYY-MM-DD. Inclusive UTC date.
      - name: to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the
            current UTC date.
          title: To
        description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current
          UTC date.
      - name: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\n\
          \    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"
  /x/stocks/v1/trending/sectors:
    get:
      tags:
      - X/Twitter Stocks
      summary: Trending sectors
      description: 'Returns the sectors with the strongest aggregated X/Twitter stock
        discussion in the selected period, ranked by `buzz_score`.


        **Includes:**

        - `buzz_score`: normalized 0-100 activity score used for ranking

        - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions, likes and author breadth; not price movement. For `from`/`to`,
        anchors at `to` (or now when `to` is today)

        - `mentions`, `unique_tickers`, `total_upvotes`: volume and engagement signals

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals

        - `top_tickers`: up to 5 tickers driving the sector result

        - `trend_history`: independent daily sector buzz scores, oldest to newest;
        length is max(requested days, 7); the live final value describes today so
        far and can differ from period `buzz_score`'
      operationId: getXTrendingSectors
      security:
      - ApiKeyAuth: []
      parameters:
      - name: from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: Start date in YYYY-MM-DD. Inclusive UTC date.
          title: From
        description: Start date in YYYY-MM-DD. Inclusive UTC date.
      - name: to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the
            current UTC date.
          title: To
        description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current
          UTC date.
      - name: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\n\
          \    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"
  /x/stocks/v1/trending/countries:
    get:
      tags:
      - X/Twitter Stocks
      summary: Trending countries
      description: 'Returns the countries with the strongest aggregated X/Twitter
        stock discussion in the selected period, ranked by `buzz_score`.


        **Includes:**

        - `buzz_score`: normalized 0-100 activity score used for ranking

        - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions, likes and author breadth; not price movement. For `from`/`to`,
        anchors at `to` (or now when `to` is today)

        - `mentions`, `unique_tickers`, `total_upvotes`: volume and engagement signals

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals

        - `top_tickers`: up to 5 tickers driving the country result

        - `trend_history`: independent daily country buzz scores, oldest to newest;
        length is max(requested days, 7); the live final value describes today so
        far and can differ from period `buzz_score`'
      operationId: getXTrendingCountries
      security:
      - ApiKeyAuth: []
      parameters:
      - name: from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: Start date in YYYY-MM-DD. Inclusive UTC date.
          title: From
        description: Start date in YYYY-MM-DD. Inclusive UTC date.
      - name: to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the
            current UTC date.
          title: To
        description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current
          UTC date.
      - name: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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 the X/Twitter report for one stock ticker.


        **Includes:**

        - `buzz_score`: normalized X/Twitter activity score for the selected period

        - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions, likes and author breadth; not price movement. For `from`/`to`,
        anchors at `to` (or now when `to` is today)

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals

        - `mentions`, `unique_tweets`, `total_upvotes`: volume and engagement signals

        - `daily_trend`: daily X/Twitter activity and sentiment values

        - `top_tweets`: representative high-engagement tweets from the selected period


        Returns `200` with `found: false` when the ticker is supported but this service

        has no qualifying data in the requested window. Returns `404` only when the

        ticker is unsupported.'
      operationId: getXStockSentiment
      security:
      - ApiKeyAuth: []
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          pattern: ^\$?(?:[A-Za-z0-9]{1,8}[.-][A-Za-z]|[A-Za-z0-9]{0}[A-Za-z][A-Za-z0-9]{0,9}|[A-Za-z0-9]{1}[A-Za-z][A-Za-z0-9]{0,8}|[A-Za-z0-9]{2}[A-Za-z][A-Za-z0-9]{0,7}|[A-Za-z0-9]{3}[A-Za-z][A-Za-z0-9]{0,6}|[A-Za-z0-9]{4}[A-Za-z][A-Za-z0-9]{0,5}|[A-Za-z0-9]{5}[A-Za-z][A-Za-z0-9]{0,4}|[A-Za-z0-9]{6}[A-Za-z][A-Za-z0-9]{0,3}|[A-Za-z0-9]{7}[A-Za-z][A-Za-z0-9]{0,2}|[A-Za-z0-9]{8}[A-Za-z][A-Za-z0-9]{0,1}|[A-Za-z0-9]{9}[A-Za-z][A-Za-z0-9]{0,0}|[0-9]{3,10})$
          description: Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A)
          examples:
          - TSLA
          title: Ticker
        description: Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A)
      - name: from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: Start date in YYYY-MM-DD. Inclusive UTC date.
          title: From
        description: Start date in YYYY-MM-DD. Inclusive UTC date.
      - name: to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the
            current UTC date.
          title: To
        description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current
          UTC date.
      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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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 one reading for all X/Twitter stock discussion: overall
        buzz, sentiment split, activity trend, breadth and the `drivers` behind it,
        ranked by `buzz_score`.


        Here `buzz_score` compares overall X stock discussion with its own trailing
        90-day baseline:

        - around `50` = normal X market activity

        - higher = more active than usual

        - lower = quieter than usual


        `trend` is activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions, likes and author breadth; not price movement. For `from`/`to`,
        anchors at `to` (or now when `to` is today).


        Use `sentiment_score`, `bullish_pct` and `bearish_pct` for direction.'
      operationId: getXMarketSentiment
      security:
      - ApiKeyAuth: []
      parameters:
      - name: from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: Start date in YYYY-MM-DD. Inclusive UTC date.
          title: From
        description: Start date in YYYY-MM-DD. Inclusive UTC date.
      - name: to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the
            current UTC date.
          title: To
        description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current
          UTC date.
      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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\n\
          \    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"
  /x/stocks/v1/stock/{ticker}/explain:
    get:
      tags:
      - X/Twitter Stocks
      summary: AI explanation
      description: 'Returns an AI-generated explanation for why a stock is trending
        on X/Twitter, anchored to tweet evidence with other platforms used only as
        cross-check context.


        **Includes:**

        - `explanation`: 1-2 sentence summary of why the stock is trending

        - `cached`: whether this was served from cache

        - `generated_at`: when the explanation was generated

        - `model`: the language model that wrote 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: google/gemma-4-31B-it-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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport requests\n\nresponse = requests.get(\n    \"\
          https://api.adanos.org/x/stocks/v1/stock/TSLA/explain\",\n    headers={\n\
          \        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n\
          )\nresponse.raise_for_status()\nprint(response.json())"
  /x/stocks/v1/compare:
    get:
      tags:
      - X/Twitter Stocks
      summary: Compare stocks
      description: 'Compare up to 10 stocks side by side using X/Twitter metrics over
        the same UTC calendar-day period.


        Use it for watchlists: one compact row per ticker.

        Results are sorted by `buzz_score` descending and include `trend`, `trend_history`,
        `mentions`, `unique_tweets`, `sentiment_score`, `bullish_pct`, `bearish_pct`
        and `total_upvotes`.

        `trend` is activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions, likes and author breadth; not price movement. For `from`/`to`,
        anchors at `to` (or now when `to` is today).

        Each requested ticker gets one row. Tickers without activity in the period,
        including unsupported ones, return zeroed metrics. Unsupported tickers have
        no company name; use `/search` to check support.'
      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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport requests\n\nresponse = requests.get(\n    \"\
          https://api.adanos.org/x/stocks/v1/search?q=tesla&limit=5\",\n    headers={\n\
          \        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n\
          )\nresponse.raise_for_status()\nprint(response.json())"
  /x/stocks/v1/stats:
    get:
      tags:
      - X/Twitter Stocks
      summary: Dataset statistics
      description: 'Returns high-level coverage and freshness metrics for the X/Twitter
        dataset.


        Includes:

        - total X mentions in the database

        - number of unique tickers with X mentions

        - today''s UTC X mention and distinct ticker counts

        - supported ticker count from the reference universe'
      operationId: getXStats
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XStatsResponse'
              example:
                total_mentions: 935
                unique_tickers: 100
                mentions_today: 42
                unique_tickers_today: 12
                supported_tickers: 35000
          headers:
            X-Request-ID:
              description: Request correlation identifier returned by the API and
                included in structured application logs.
              schema:
                type: string
              example: adnos.req-20260423.abc12345
            Cache-Control:
              description: HTTP cache policy returned by the API.
              schema:
                type: string
              example: private, max-age=300
            Vary:
              description: Headers that private client caches must include in their
                cache key.
              schema:
                type: string
              example: X-API-Key, Authorization, Accept-Encoding
            X-RateLimit-Limit-Monthly:
              description: Monthly request quota for the authenticated account.
              schema:
                type: string
              example: '250'
            X-RateLimit-Remaining-Monthly:
              description: Remaining monthly requests for the authenticated account.
              schema:
                type: string
              example: '247'
            X-RateLimit-Used-Monthly:
              description: Requests already consumed in the account's current monthly
                quota window.
              schema:
                type: string
              example: '3'
            X-RateLimit-Reset-Monthly:
              description: ISO 8601 timestamp when the current monthly quota window
                resets.
              schema:
                type: string
                format: date-time
              example: '2026-07-29T14:03:00Z'
            X-RateLimit-Limit-Burst:
              description: Per-minute burst request quota for the authenticated account.
              schema:
                type: string
              example: '100'
            X-RateLimit-Remaining-Burst:
              description: Remaining requests in the current per-minute burst window.
              schema:
                type: string
              example: '99'
            X-RateLimit-Reset-Burst:
              description: ISO 8601 timestamp when the current burst rate-limit window
                resets.
              schema:
                type: string
                format: date-time
              example: '2026-04-28T14:30:00Z'
            X-Account-Type:
              description: Account tier resolved from the API key.
              schema:
                type: string
                enum:
                - free
                - hobby
                - professional
                - premium
              example: free
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing:
                  summary: Missing API key
                  value:
                    detail: Missing API key. Include 'X-API-Key' header.
                invalid:
                  summary: Invalid API key
                  value:
                    detail: Invalid API key.
                revoked:
                  summary: Revoked API key
                  value:
                    detail: API key has been revoked.
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
              examples:
                burst:
                  summary: Fleet burst limit exceeded
                  value:
                    detail:
                      error: Burst rate limit exceeded
                      message: Too many requests. Limit is 100 requests per minute.
                      limit: 100
                      used: 100
                      account_type: free
                local:
                  summary: Local backup limiter exceeded
                  value:
                    detail:
                      error: Rate limit exceeded
                      message: 'Rate limit exceeded: 100 per 1 minute'
                      limit: 100
                      account_type: free
        '503':
          description: Database temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Database temporarily unavailable
        '504':
          description: Analytics request deadline exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Request deadline exceeded
      security:
      - ApiKeyAuth: []
      x-codeSamples:
      - lang: curl
        label: cURL
        source: "curl \"https://api.adanos.org/x/stocks/v1/stats\" \\\n  -H \"X-API-Key:\
          \ $ADANOS_API_KEY\""
      - lang: javascript
        label: JavaScript
        source: "const response = await fetch(\"https://api.adanos.org/x/stocks/v1/stats\"\
          , {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\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 os\n\nimport requests\n\nresponse = requests.get(\n    \"\
          https://api.adanos.org/x/stocks/v1/stats\",\n    headers={\n        \"X-API-Key\"\
          : os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\n\
          print(response.json())"
  /x/stocks/v1/stock/{ticker}/mentions:
    get:
      tags:
      - X/Twitter Stocks
      summary: Raw mentions
      description: 'Returns raw tweet rows for a specific ticker within the live raw-data
        retention window.

        **Professional account required.** Free and Hobby accounts cannot use this
        endpoint.


        **Use this endpoint when you need:**

        - tweet-level snippets

        - original timestamps

        - engagement counters on the raw rows


        **Notes:**

        - Use `from` and `to` for explicit UTC date windows

        - Results are ordered newest first and support deterministic `offset` + `limit`
        pagination

        - empty result sets return `200` with `results=[]`'
      operationId: getXStockRawMentions
      security:
      - ApiKeyAuth: []
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          pattern: ^\$?(?:[A-Za-z0-9]{1,8}[.-][A-Za-z]|[A-Za-z0-9]{0}[A-Za-z][A-Za-z0-9]{0,9}|[A-Za-z0-9]{1}[A-Za-z][A-Za-z0-9]{0,8}|[A-Za-z0-9]{2}[A-Za-z][A-Za-z0-9]{0,7}|[A-Za-z0-9]{3}[A-Za-z][A-Za-z0-9]{0,6}|[A-Za-z0-9]{4}[A-Za-z][A-Za-z0-9]{0,5}|[A-Za-z0-9]{5}[A-Za-z][A-Za-z0-9]{0,4}|[A-Za-z0-9]{6}[A-Za-z][A-Za-z0-9]{0,3}|[A-Za-z0-9]{7}[A-Za-z][A-Za-z0-9]{0,2}|[A-Za-z0-9]{8}[A-Za-z][A-Za-z0-9]{0,1}|[A-Za-z0-9]{9}[A-Za-z][A-Za-z0-9]{0,0}|[0-9]{3,10})$
          description: Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A)
          examples:
          - TSLA
          - BRK.A
          title: Ticker
        description: Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A)
      - name: from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: Start date in YYYY-MM-DD. Inclusive UTC date.
          title: From
        description: Start date in YYYY-MM-DD. Inclusive UTC date.
      - name: to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the
            current UTC date.
          title: To
        description: End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current
          UTC date.
      - name: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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`.


        **Includes:**

        - `buzz_score`: normalized 0-100 activity score used for ranking; bullish
        and bearish market activity can both rank highly

        - `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)

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: outcome-aware market sentiment
        signals

        - `trade_count`, `market_count`, `unique_traders`, `total_liquidity`: activity,
        breadth, observed participation and liquidity signals

        - `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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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`.


        **Includes:**

        - `buzz_score`: normalized 0-100 activity score used for ranking

        - `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)

        - `trade_count`, `market_count`, `unique_traders`, `total_liquidity`: activity,
        breadth, observed participation and liquidity signals

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: outcome-aware market sentiment
        signals

        - `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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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`.


        **Includes:**

        - `buzz_score`: normalized 0-100 activity score used for ranking

        - `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)

        - `trade_count`, `market_count`, `unique_traders`, `total_liquidity`: activity,
        breadth, observed participation and liquidity signals

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: outcome-aware market sentiment
        signals

        - `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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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.


        The response combines:

        - Period metrics for the date window defined by `from`/`to`.

        - Representative market-level evidence in `top_mentions`.

        - A compact current market read in `pulse`.


        **Fields:**

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: outcome-aware sentiment
        derived from Polymarket market prices and outcomes

        - `buzz_score`: normalized activity score for the selected period; both bullish
        and bearish activity can increase buzz

        - `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

        - `trade_count`, `market_count`, `unique_traders`, `total_liquidity`: period
        activity, breadth, observed participation and liquidity

        - `daily_trend`: daily activity and sentiment values for the selected window

        - `top_mentions`: representative Polymarket markets behind the ticker-level
        signals, including market-level `sentiment_score` and `buzz_score`

        - `pulse`: compact current interpretation from the latest stored open-market
        snapshots


        **Notes:**

        - `pulse` describes the current state and does not repeat the aggregate fields.
        Use `top_mentions` for concrete market examples.

        - `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.

        - Prices, volume and liquidity in `top_mentions` come from the selected in-period
        snapshot, not necessarily the latest live market state.

        - `active` indicates whether the market is currently open, so older in-period
        evidence can now be inactive, resolved or expired.

        - `market_status` can be `tradable`, `open`, `resolved`, `expired` or `inactive`.

        - For windows longer than snapshot retention, aggregate metrics still come
        from daily aggregates, while `top_mentions` is limited to retained market
        snapshots.

        - 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.
      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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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 one reading for all stock-related Polymarket activity:
        overall buzz, sentiment split, activity trend, breadth and the `drivers` behind
        it, ranked by `buzz_score`.


        Here `buzz_score` compares overall Polymarket stock-market activity with its
        own trailing 90-day baseline:

        - around `50` = normal market activity

        - higher = more active than usual

        - lower = quieter than usual


        `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).


        Use `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.
      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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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.


        Use it for watchlists: one compact row per ticker.

        Results 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`.

        `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).

        Each requested ticker gets one row. Tickers without activity in the period,
        including unsupported ones, return zeroed metrics. Unsupported tickers have
        no company name; use `/search` to check support.'
      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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport requests\n\nresponse = requests.get(\n    \"\
          https://api.adanos.org/polymarket/stocks/v1/search?q=tesla&limit=5\",\n\
          \    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n\
          \    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"
  /polymarket/stocks/v1/stats:
    get:
      tags:
      - Polymarket Stocks
      summary: Dataset statistics
      description: 'Returns high-level database coverage metrics for the Polymarket
        stock dataset.


        Use this endpoint to understand how much market activity is indexed:

        - total aggregated trade activity

        - total distinct markets captured

        - unique stock tickers with indexed Polymarket market rows

        - currently open markets and tickers

        - today''s UTC trade activity, traded markets and traded tickers

        - 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: 35000
          headers:
            X-Request-ID:
              description: Request correlation identifier returned by the API and
                included in structured application logs.
              schema:
                type: string
              example: adnos.req-20260423.abc12345
            Cache-Control:
              description: HTTP cache policy returned by the API.
              schema:
                type: string
              example: private, max-age=300
            Vary:
              description: Headers that private client caches must include in their
                cache key.
              schema:
                type: string
              example: X-API-Key, Authorization, Accept-Encoding
            X-RateLimit-Limit-Monthly:
              description: Monthly request quota for the authenticated account.
              schema:
                type: string
              example: '250'
            X-RateLimit-Remaining-Monthly:
              description: Remaining monthly requests for the authenticated account.
              schema:
                type: string
              example: '247'
            X-RateLimit-Used-Monthly:
              description: Requests already consumed in the account's current monthly
                quota window.
              schema:
                type: string
              example: '3'
            X-RateLimit-Reset-Monthly:
              description: ISO 8601 timestamp when the current monthly quota window
                resets.
              schema:
                type: string
                format: date-time
              example: '2026-07-29T14:03:00Z'
            X-RateLimit-Limit-Burst:
              description: Per-minute burst request quota for the authenticated account.
              schema:
                type: string
              example: '100'
            X-RateLimit-Remaining-Burst:
              description: Remaining requests in the current per-minute burst window.
              schema:
                type: string
              example: '99'
            X-RateLimit-Reset-Burst:
              description: ISO 8601 timestamp when the current burst rate-limit window
                resets.
              schema:
                type: string
                format: date-time
              example: '2026-04-28T14:30:00Z'
            X-Account-Type:
              description: Account tier resolved from the API key.
              schema:
                type: string
                enum:
                - free
                - hobby
                - professional
                - premium
              example: free
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing:
                  summary: Missing API key
                  value:
                    detail: Missing API key. Include 'X-API-Key' header.
                invalid:
                  summary: Invalid API key
                  value:
                    detail: Invalid API key.
                revoked:
                  summary: Revoked API key
                  value:
                    detail: API key has been revoked.
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
              examples:
                burst:
                  summary: Fleet burst limit exceeded
                  value:
                    detail:
                      error: Burst rate limit exceeded
                      message: Too many requests. Limit is 100 requests per minute.
                      limit: 100
                      used: 100
                      account_type: free
                local:
                  summary: Local backup limiter exceeded
                  value:
                    detail:
                      error: Rate limit exceeded
                      message: 'Rate limit exceeded: 100 per 1 minute'
                      limit: 100
                      account_type: free
        '503':
          description: Database temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Database temporarily unavailable
        '504':
          description: Analytics request deadline exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Request deadline exceeded
      security:
      - ApiKeyAuth: []
      x-codeSamples:
      - lang: curl
        label: cURL
        source: "curl \"https://api.adanos.org/polymarket/stocks/v1/stats\" \\\n \
          \ -H \"X-API-Key: $ADANOS_API_KEY\""
      - lang: javascript
        label: JavaScript
        source: "const response = await fetch(\"https://api.adanos.org/polymarket/stocks/v1/stats\"\
          , {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\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 os\n\nimport requests\n\nresponse = requests.get(\n    \"\
          https://api.adanos.org/polymarket/stocks/v1/stats\",\n    headers={\n  \
          \      \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\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.

        **Professional account required.** Free and Hobby accounts cannot use this
        endpoint.


        **Use this endpoint when you need:**

        - original market questions, prices, liquidity, volume, trade counters and
        timestamps

        - outcome-aware market price sentiment for individual snapshot rows

        - repeated snapshots for the same market over time


        **Notes:**

        - Use `from` and `to` for explicit UTC date windows

        - Results are ordered newest first and support deterministic `offset` + `limit`
        pagination

        - empty result sets return `200` with `results=[]`

        - The same `condition_id` can appear multiple times across different `fetched_at`
        snapshots

        - `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`

        - `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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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`.


        **Includes:**

        - `buzz_score`: normalized 0-100 activity score used for ranking

        - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions/articles and source breadth; not price movement. For `from`/`to`,
        anchors at `to` (or now when `to` is today)

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals

        - `mentions`, `source_count`: coverage volume and source breadth signals

        - `trend_history`: independent UTC-day buzz scores, oldest to newest; minimum
        7 values; the live final value describes today so far and can differ from
        the selected-period `buzz_score`; missing days are `0.0`


        Use `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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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`.


        **Includes:**

        - `buzz_score`: normalized 0-100 activity score used for ranking

        - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions/articles and source breadth; not price movement. For `from`/`to`,
        anchors at `to` (or now when `to` is today)

        - `mentions`, `unique_tickers`, `source_count`: coverage volume and breadth
        signals

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals

        - `top_tickers`: up to 5 tickers driving the sector result


        Use `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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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`.


        **Includes:**

        - `buzz_score`: normalized 0-100 activity score used for ranking

        - `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC
        days using mentions/articles and source breadth; not price movement. For `from`/`to`,
        anchors at `to` (or now when `to` is today)

        - `mentions`, `unique_tickers`, `source_count`: coverage volume and breadth
        signals

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals

        - `top_tickers`: up to 5 tickers driving the country result


        Use `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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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: 'Returns the news report for one stock ticker.


        **Includes:**

        - `buzz_score`: normalized news activity score for the selected period

        - `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)

        - `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals

        - `mentions`, `source_count`: coverage volume and source breadth signals

        - `daily_trend`: daily news activity and sentiment values

        - `top_mentions`: representative recent articles from the selected period,
        with source attribution

        - `top_sources`: top source contributors by mention count


        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: getNewsStockSentiment
      security:
      - ApiKeyAuth: []
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          pattern: ^(?=[A-Za-z0-9.]{1,32}$)[A-Za-z0-9]+(?:\.(?:[Aa][Ee]|[Aa][Ss]|[Aa][Tt]|[Aa][Xx]|[Bb][Aa]|[Bb][Dd]|[Bb][Kk]|[Bb][Oo]|[Bb][Rr]|[Cc][Aa]|[Cc][Ll]|[Cc][Nn]|[Cc][Oo]|[Dd][Ee]|[Dd][Uu]|[Ff]|[Hh][Aa]|[Hh][Ee]|[Hh][Kk]|[Hh][Mm]|[Ii][Cc]|[Ii][Rr]|[Ii][Ss]|[Jj][Kk]|[Jj][Oo]|[Kk][Ll]|[Kk][Qq]|[Kk][Ss]|[Kk][Ww]|[Ll]|[Ll][Ss]|[Mm][Cc]|[Mm][Ii]|[Mm][Uu]|[Mm][Xx]|[Nn][Ee]|[Nn][Ss]|[Nn][Zz]|[Oo][Ll]|[Pp][Aa]|[Pp][Rr]|[Pp][Ss]|[Qq][Aa]|[Rr][Oo]|[Ss][Aa]|[Ss][Aa][Uu]|[Ss][Gg]|[Ss][Ii]|[Ss][Nn]|[Ss][Ss]|[Ss][Tt]|[Ss][Ww]|[Ss][Zz]|[Tt]|[Tt][Aa]|[Tt][Oo]|[Tt][Ww]|[Tt][Ww][Oo]|[Vv]|[Vv][Ii]|[Vv][Nn]|[Ww][Aa]))?$(?![\s\S])
          description: 'News company key: 1-32 ASCII letters/digits with an optional
            documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE.
            Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and
            unknown suffixes return 422. A documented suffix resolves only if assigned
            to that issuer; other well-formed keys return 404. One issuer is one time
            series; ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX,
            .BA, .BD, .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK,
            .HM, .IC, .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU,
            .MX, .NE, .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI,
            .SN, .SS, .ST, .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA.'
          title: Ticker
        description: 'News company key: 1-32 ASCII letters/digits with an optional
          documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE.
          Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and unknown
          suffixes return 422. A documented suffix resolves only if assigned to that
          issuer; other well-formed keys return 404. One issuer is one time series;
          ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX, .BA, .BD,
          .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK, .HM, .IC,
          .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU, .MX, .NE,
          .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI, .SN, .SS, .ST,
          .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA.'
      - 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.
      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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              schema:
                anyOf:
                - $ref: '#/components/schemas/InvalidPeriodError'
                - $ref: '#/components/schemas/HTTPValidationError'
                title: Response 422 Getnewsstocksentiment
        '503':
          description: News identity lookup or database service unavailable; no Legacy
            fallback is used
          content:
            application/json:
              example:
                detail: News identity lookup 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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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 one reading for all stock news coverage: overall buzz,
        sentiment split, activity trend, breadth and the `drivers` behind it, ranked
        by `buzz_score`.


        Here `buzz_score` compares overall stock news flow with its own trailing 90-day
        baseline:

        - around `50` = normal news activity

        - higher = broader coverage than usual

        - lower = quieter than usual


        `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).


        Use `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.
      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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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.


        **Includes:**

        - `explanation`: 1-2 sentence summary of why the stock is trending

        - `cached`: whether this was served from cache

        - `generated_at`: when the explanation was generated

        - `model`: the language model that wrote the explanation'
      operationId: getNewsStockExplanation
      security:
      - ApiKeyAuth: []
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          pattern: ^(?=[A-Za-z0-9.]{1,32}$)[A-Za-z0-9]+(?:\.(?:[Aa][Ee]|[Aa][Ss]|[Aa][Tt]|[Aa][Xx]|[Bb][Aa]|[Bb][Dd]|[Bb][Kk]|[Bb][Oo]|[Bb][Rr]|[Cc][Aa]|[Cc][Ll]|[Cc][Nn]|[Cc][Oo]|[Dd][Ee]|[Dd][Uu]|[Ff]|[Hh][Aa]|[Hh][Ee]|[Hh][Kk]|[Hh][Mm]|[Ii][Cc]|[Ii][Rr]|[Ii][Ss]|[Jj][Kk]|[Jj][Oo]|[Kk][Ll]|[Kk][Qq]|[Kk][Ss]|[Kk][Ww]|[Ll]|[Ll][Ss]|[Mm][Cc]|[Mm][Ii]|[Mm][Uu]|[Mm][Xx]|[Nn][Ee]|[Nn][Ss]|[Nn][Zz]|[Oo][Ll]|[Pp][Aa]|[Pp][Rr]|[Pp][Ss]|[Qq][Aa]|[Rr][Oo]|[Ss][Aa]|[Ss][Aa][Uu]|[Ss][Gg]|[Ss][Ii]|[Ss][Nn]|[Ss][Ss]|[Ss][Tt]|[Ss][Ww]|[Ss][Zz]|[Tt]|[Tt][Aa]|[Tt][Oo]|[Tt][Ww]|[Tt][Ww][Oo]|[Vv]|[Vv][Ii]|[Vv][Nn]|[Ww][Aa]))?$(?![\s\S])
          description: 'News company key: 1-32 ASCII letters/digits with an optional
            documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE.
            Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and
            unknown suffixes return 422. A documented suffix resolves only if assigned
            to that issuer; other well-formed keys return 404. One issuer is one time
            series; ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX,
            .BA, .BD, .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK,
            .HM, .IC, .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU,
            .MX, .NE, .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI,
            .SN, .SS, .ST, .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA.'
          title: Ticker
        description: 'News company key: 1-32 ASCII letters/digits with an optional
          documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE.
          Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and unknown
          suffixes return 422. A documented suffix resolves only if assigned to that
          issuer; other well-formed keys return 404. One issuer is one time series;
          ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX, .BA, .BD,
          .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK, .HM, .IC,
          .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU, .MX, .NE,
          .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI, .SN, .SS, .ST,
          .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA.'
      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: google/gemma-4-31B-it-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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport requests\n\nresponse = requests.get(\n    \"\
          https://api.adanos.org/news/stocks/v1/stock/TSLA/explain\",\n    headers={\n\
          \        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\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 up to 10 companies side by side using news coverage.


        Use it for watchlists: one compact row per ticker.

        Results are sorted by `buzz_score` descending and include `trend`, `trend_history`,
        `source_count`, `sentiment_score`, `bullish_pct` and `bearish_pct`.

        `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).

        Each requested ticker gets one row. Tickers without activity in the period,
        including unsupported ones, return zeroed metrics. Unsupported tickers have
        no company name; use `/search` to check support.'
      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: tickers
        in: query
        required: true
        schema:
          type: string
          maxLength: 512
          description: 'Comma-separated News tickers. News company key: 1-32 ASCII
            letters/digits with an optional documented venue suffix, case-insensitive.
            Examples: BRK, EADSY, ABX.DE. Share classes (BRK.A, BRK.B, BRK-B), hyphens,
            ampersands, cashtags and unknown suffixes return 422. A documented suffix
            resolves only if assigned to that issuer; other well-formed keys return
            404. One issuer is one time series; ETFs stay separate issuers. Venue
            suffixes: .AE, .AS, .AT, .AX, .BA, .BD, .BK, .BO, .BR, .CA, .CL, .CN,
            .CO, .DE, .DU, .F, .HA, .HE, .HK, .HM, .IC, .IR, .IS, .JK, .JO, .KL, .KQ,
            .KS, .KW, .L, .LS, .MC, .MI, .MU, .MX, .NE, .NS, .NZ, .OL, .PA, .PR, .PS,
            .QA, .RO, .SA, .SAU, .SG, .SI, .SN, .SS, .ST, .SW, .SZ, .T, .TA, .TO,
            .TW, .TWO, .V, .VI, .VN, .WA. Unknown keys and known companies without
            activity return zero-activity entries; Compare does not distinguish these
            states. Ambiguous identities return 404.'
          title: Tickers
        description: 'Comma-separated News tickers. News company key: 1-32 ASCII letters/digits
          with an optional documented venue suffix, case-insensitive. Examples: BRK,
          EADSY, ABX.DE. Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands,
          cashtags and unknown suffixes return 422. A documented suffix resolves only
          if assigned to that issuer; other well-formed keys return 404. One issuer
          is one time series; ETFs stay separate issuers. Venue suffixes: .AE, .AS,
          .AT, .AX, .BA, .BD, .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA,
          .HE, .HK, .HM, .IC, .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC,
          .MI, .MU, .MX, .NE, .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG,
          .SI, .SN, .SS, .ST, .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA.
          Unknown keys and known companies without activity return zero-activity entries;
          Compare does not distinguish these states. Ambiguous identities return 404.'
      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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              schema:
                anyOf:
                - $ref: '#/components/schemas/InvalidPeriodError'
                - $ref: '#/components/schemas/HTTPValidationError'
                title: Response 422 Comparenewsstocks
        '503':
          description: News identity lookup or database service unavailable; no Legacy
            fallback is used
          content:
            application/json:
              example:
                detail: News identity lookup 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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\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:
                  - TSLA
                  - NASDAQ:TSLA
                  - Tesla
                  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: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport requests\n\nresponse = requests.get(\n    \"\
          https://api.adanos.org/news/stocks/v1/search?q=tesla&limit=5\",\n    headers={\n\
          \        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n\
          )\nresponse.raise_for_status()\nprint(response.json())"
  /news/stocks/v1/stats:
    get:
      tags:
      - News Stocks
      summary: Dataset statistics
      description: 'Returns high-level coverage statistics for the news stocks dataset.


        Includes:

        - total mention rows stored

        - distinct tickers with news data

        - today''s UTC mention and distinct ticker counts

        - 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: 35000
          headers:
            X-Request-ID:
              description: Request correlation identifier returned by the API and
                included in structured application logs.
              schema:
                type: string
              example: adnos.req-20260423.abc12345
            Cache-Control:
              description: HTTP cache policy returned by the API.
              schema:
                type: string
              example: private, max-age=300
            Vary:
              description: Headers that private client caches must include in their
                cache key.
              schema:
                type: string
              example: X-API-Key, Authorization, Accept-Encoding
            X-RateLimit-Limit-Monthly:
              description: Monthly request quota for the authenticated account.
              schema:
                type: string
              example: '250'
            X-RateLimit-Remaining-Monthly:
              description: Remaining monthly requests for the authenticated account.
              schema:
                type: string
              example: '247'
            X-RateLimit-Used-Monthly:
              description: Requests already consumed in the account's current monthly
                quota window.
              schema:
                type: string
              example: '3'
            X-RateLimit-Reset-Monthly:
              description: ISO 8601 timestamp when the current monthly quota window
                resets.
              schema:
                type: string
                format: date-time
              example: '2026-07-29T14:03:00Z'
            X-RateLimit-Limit-Burst:
              description: Per-minute burst request quota for the authenticated account.
              schema:
                type: string
              example: '100'
            X-RateLimit-Remaining-Burst:
              description: Remaining requests in the current per-minute burst window.
              schema:
                type: string
              example: '99'
            X-RateLimit-Reset-Burst:
              description: ISO 8601 timestamp when the current burst rate-limit window
                resets.
              schema:
                type: string
                format: date-time
              example: '2026-04-28T14:30:00Z'
            X-Account-Type:
              description: Account tier resolved from the API key.
              schema:
                type: string
                enum:
                - free
                - hobby
                - professional
                - premium
              example: free
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing:
                  summary: Missing API key
                  value:
                    detail: Missing API key. Include 'X-API-Key' header.
                invalid:
                  summary: Invalid API key
                  value:
                    detail: Invalid API key.
                revoked:
                  summary: Revoked API key
                  value:
                    detail: API key has been revoked.
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
              examples:
                burst:
                  summary: Fleet burst limit exceeded
                  value:
                    detail:
                      error: Burst rate limit exceeded
                      message: Too many requests. Limit is 100 requests per minute.
                      limit: 100
                      used: 100
                      account_type: free
                local:
                  summary: Local backup limiter exceeded
                  value:
                    detail:
                      error: Rate limit exceeded
                      message: 'Rate limit exceeded: 100 per 1 minute'
                      limit: 100
                      account_type: free
        '503':
          description: Database temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Database temporarily unavailable
        '504':
          description: Analytics request deadline exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Request deadline exceeded
        '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: $ADANOS_API_KEY\""
      - lang: javascript
        label: JavaScript
        source: "const response = await fetch(\"https://api.adanos.org/news/stocks/v1/stats\"\
          , {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\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 os\n\nimport requests\n\nresponse = requests.get(\n    \"\
          https://api.adanos.org/news/stocks/v1/stats\",\n    headers={\n        \"\
          X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\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.

        **Professional account required.** Free and Hobby accounts cannot use this
        endpoint.


        **Use this endpoint when you need:**

        - article-level snippets

        - original timestamps

        - source attribution for raw rows


        **Notes:**

        - Use `from` and `to` for explicit UTC date windows

        - Results are ordered newest first and support deterministic `offset` + `limit`
        pagination

        - supported tickers with no rows return `200` with `results=[]`

        - unsupported tickers return `404`, regardless of the requested window or
        offset'
      operationId: getNewsStockMentions
      security:
      - ApiKeyAuth: []
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          pattern: ^(?=[A-Za-z0-9.]{1,32}$)[A-Za-z0-9]+(?:\.(?:[Aa][Ee]|[Aa][Ss]|[Aa][Tt]|[Aa][Xx]|[Bb][Aa]|[Bb][Dd]|[Bb][Kk]|[Bb][Oo]|[Bb][Rr]|[Cc][Aa]|[Cc][Ll]|[Cc][Nn]|[Cc][Oo]|[Dd][Ee]|[Dd][Uu]|[Ff]|[Hh][Aa]|[Hh][Ee]|[Hh][Kk]|[Hh][Mm]|[Ii][Cc]|[Ii][Rr]|[Ii][Ss]|[Jj][Kk]|[Jj][Oo]|[Kk][Ll]|[Kk][Qq]|[Kk][Ss]|[Kk][Ww]|[Ll]|[Ll][Ss]|[Mm][Cc]|[Mm][Ii]|[Mm][Uu]|[Mm][Xx]|[Nn][Ee]|[Nn][Ss]|[Nn][Zz]|[Oo][Ll]|[Pp][Aa]|[Pp][Rr]|[Pp][Ss]|[Qq][Aa]|[Rr][Oo]|[Ss][Aa]|[Ss][Aa][Uu]|[Ss][Gg]|[Ss][Ii]|[Ss][Nn]|[Ss][Ss]|[Ss][Tt]|[Ss][Ww]|[Ss][Zz]|[Tt]|[Tt][Aa]|[Tt][Oo]|[Tt][Ww]|[Tt][Ww][Oo]|[Vv]|[Vv][Ii]|[Vv][Nn]|[Ww][Aa]))?$(?![\s\S])
          description: 'News company key: 1-32 ASCII letters/digits with an optional
            documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE.
            Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and
            unknown suffixes return 422. A documented suffix resolves only if assigned
            to that issuer; other well-formed keys return 404. One issuer is one time
            series; ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX,
            .BA, .BD, .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK,
            .HM, .IC, .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU,
            .MX, .NE, .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI,
            .SN, .SS, .ST, .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA.'
          title: Ticker
        description: 'News company key: 1-32 ASCII letters/digits with an optional
          documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE.
          Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and unknown
          suffixes return 422. A documented suffix resolves only if assigned to that
          issuer; other well-formed keys return 404. One issuer is one time series;
          ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX, .BA, .BD,
          .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK, .HM, .IC,
          .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU, .MX, .NE,
          .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI, .SN, .SS, .ST,
          .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA.'
      - 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: 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: date_from_datetime_parsing
                      loc:
                      - query
                      - from
                      msg: Input should be a valid date or datetime, month value is
                        outside expected range of 1-12
                      input: '2026-13-01'
                      ctx:
                        error: month value is outside expected range of 1-12
              schema:
                anyOf:
                - $ref: '#/components/schemas/InvalidPeriodError'
                - $ref: '#/components/schemas/HTTPValidationError'
                title: Response 422 Getnewsstockmentions
        '503':
          description: News identity lookup or database service unavailable; no Legacy
            fallback is used
          content:
            application/json:
              example:
                detail: News identity lookup 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/mentions?from=2026-05-01&to=2026-05-07&limit=5\"\
          \ \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""
      - 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\": process.env.ADANOS_API_KEY,\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 os\n\nimport 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\": os.environ[\"ADANOS_API_KEY\"],\n\
          \    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"
  /reddit/stocks/v1/health:
    get:
      tags:
      - Health-Check
      summary: Reddit Stocks health
      description: 'Shows whether Reddit Stocks data collection is running and when
        it last ran. No API key needed.


        `scheduler.last_scrape` is the time of the most recent collection. For data,
        use `/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.53.4
                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");


          if (!response.ok) throw new Error(`HTTP ${response.status}`);

          const data = await response.json();

          console.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 health
      description: 'Shows whether Reddit Crypto data collection is running and when
        it last ran. No API key needed.


        `scheduler.last_scrape` is the time of the most recent collection. For data,
        use `/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.53.4
                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");


          if (!response.ok) throw new Error(`HTTP ${response.status}`);

          const data = await response.json();

          console.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 health
      description: 'Shows whether X/Twitter data collection is running and when it
        last ran. No API key needed.


        `scheduler.last_scrape` is the time of the most recent collection. For data,
        use `/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.53.4
                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");


          if (!response.ok) throw new Error(`HTTP ${response.status}`);

          const data = await response.json();

          console.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 health
      description: 'Shows whether Polymarket data collection is running and when it
        last ran. No API key needed.


        `scheduler.last_scrape` is the time of the most recent collection. For data,
        use `/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.53.4
                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");


          if (!response.ok) throw new Error(`HTTP ${response.status}`);

          const data = await response.json();

          console.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 health
      description: 'Shows whether News data collection is running and when it last
        ran. No API key needed.


        `scheduler.last_scrape` is the time of the most recent collection. For data,
        use `/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.53.4
                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");


          if (!response.ok) throw new Error(`HTTP ${response.status}`);

          const data = await response.json();

          console.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: API health
      description: 'Checks the database and data collection for every platform in
        one call.


        No API key needed. This check is slower than the per-platform `/health`

        endpoints, so poll those for routine monitoring.'
      operationId: getRootHealth
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RootHealthResponse'
              example:
                status: healthy
                service: adanos-api
                version: 1.53.4
                summary:
                  total: 5
                  healthy: 5
                  unhealthy: 0
                  unhealthy_services: []
                services:
                  news-stocks:
                    service: news-stocks
                    status: healthy
                    version: 1.53.4
                  polymarket-stocks:
                    service: polymarket-stocks
                    status: healthy
                    version: 1.53.4
                  reddit-crypto:
                    service: reddit-crypto
                    status: healthy
                    version: 1.53.4
                  reddit-stocks:
                    service: reddit-stocks
                    status: healthy
                    version: 1.53.4
                  x-stocks:
                    service: x-stocks
                    status: healthy
                    version: 1.53.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: 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.53.4
                summary:
                  total: 5
                  healthy: 5
                  unhealthy: 0
                  unhealthy_services: []
                services:
                  news-stocks:
                    service: news-stocks
                    status: healthy
                    version: 1.53.4
                  polymarket-stocks:
                    service: polymarket-stocks
                    status: healthy
                    version: 1.53.4
                  reddit-crypto:
                    service: reddit-crypto
                    status: healthy
                    version: 1.53.4
                  reddit-stocks:
                    service: reddit-stocks
                    status: healthy
                    version: 1.53.4
                  x-stocks:
                    service: x-stocks
                    status: healthy
                    version: 1.53.4
      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");


          if (!response.ok) throw new Error(`HTTP ${response.status}`);

          const data = await response.json();

          console.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.


        Returns the sentiment of one financial text, such as a news headline or a
        sentence about a company. Pass `target` (for example `Apple` or `AAPL`) to
        get the sentiment for that company. Scored by Adanos News Sentiment 5.5, our
        own model built for financial news.'
      operationId: analyzeSentimentText
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SentimentAnalyzeRequest'
            example:
              text: Apple beats earnings estimates and raises its dividend
              target: Apple
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SentimentAnalyzeResponse'
              example:
                text: Apple beats earnings estimates and raises its dividend
                sentiment_score: 0.999
                sentiment_label: positive
                components:
                  engine_version: '5.5'
                  model_score: 0.9988
                  emoji_score: 0.0
                  phrase_adjustment: 0.0
                  phrase_matches: []
                  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
          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: Net upvotes (Reddit score) across attributed mentions; negative
            when downvotes prevail
          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: Buzz score for this date (0-100); null until the day is aggregated,
            while the activity fields are already filled
          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.53.4
        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.53.4
        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 5 tokens of the selected period by buzz_score. mentions
            and sentiment_score cover every day of the period.
      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: UTC timestamp of creation (ISO 8601)
          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 data collection is running
        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 collection attempts 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: Reddit Crypto data collection 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: All-time number of stored Reddit Crypto mentions
          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: Net upvotes (Reddit score) across attributed mentions; negative
            when downvotes prevail
        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: UTC timestamp of creation (ISO 8601)
      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: Net upvotes (Reddit score) across attributed mentions; negative
            when downvotes prevail
          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); null until the day is aggregated,
            while the activity fields are already filled
          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
          - limit
          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.53.4
        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.53.4
        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 or fund name from resolved instrument metadata or the
            Legacy 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:
          - TSLA
          - NASDAQ:TSLA
          - Tesla
          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: Configured News graph matching terms, including terms with
            no mentions in the summary window; article acceptance also depends on
            worker safety and context checks
          examples:
          - - TSLA
            - NASDAQ:TSLA
            - Tesla
        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: All-time number of stored news stock mentions
          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 public tickers in the News reference catalog
          examples:
          - 35000
      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: 35000
    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 or fund name from resolved instrument metadata or the
            Legacy reference (null if unavailable)
          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 or fund name from resolved instrument metadata or the
            Legacy reference (null if unavailable)
          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
        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.53.4
        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.53.4
        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 5 stocks of the selected period by buzz_score. trade_count
            and sentiment_score cover every day of the period.
      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 data collection is running
        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 data collection 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: Number of supported stock tickers
      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: 35000
    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
          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 daily aggregates,
            while this list is limited to retained 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
          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 5 stocks of the selected period by buzz_score. mentions
            and sentiment_score cover every day of the period.
      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: UTC timestamp of creation (ISO 8601)
          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: All-time number of stored Reddit stock mentions
          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 stock tickers
          examples:
          - 35000
      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: 35000
    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.53.4
        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.53.4
        summary:
          total: 5
          healthy: 5
          unhealthy: 0
          unhealthy_services: []
        services:
          news-stocks:
            service: news-stocks
            status: healthy
            version: 1.53.4
          polymarket-stocks:
            service: polymarket-stocks
            status: healthy
            version: 1.53.4
          reddit-crypto:
            service: reddit-crypto
            status: healthy
            version: 1.53.4
          reddit-stocks:
            service: reddit-stocks
            status: healthy
            version: 1.53.4
          x-stocks:
            service: x-stocks
            status: healthy
            version: 1.53.4
    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 data collection is running
        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 status information, for example why collection is
            not running
      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 text to analyze, for example a news headline or a
            sentence about a company.
          examples:
          - Apple beats earnings estimates and raises its dividend
        target:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Target
          description: 'Optional: the company to judge the text for, as a name or
            ticker, for example `Apple` or `AAPL`. It should appear in the text; a
            company name works best. "Goldman Sachs cuts Apple price target" is negative
            for `Apple` and neutral for `Goldman Sachs`.'
          examples:
          - Apple
      type: object
      required:
      - text
      title: SentimentAnalyzeRequest
      description: Direct text sentiment analysis request.
      examples:
      - text: Apple beats earnings estimates and raises its dividend
        target: Apple
    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: Apple beats earnings estimates and raises its dividend
        sentiment_score: 0.999
        sentiment_label: positive
        components:
          engine_version: '5.5'
          model_score: 0.9988
          emoji_score: 0.0
          phrase_adjustment: 0.0
          phrase_matches: []
          contextual_finance_matches: []
    SentimentComponents:
      properties:
        engine_version:
          type: string
          title: Engine Version
          description: Sentiment engine version
          examples:
          - '5.5'
        model_score:
          anyOf:
          - type: number
            maximum: 1.0
            minimum: -1.0
          - type: 'null'
          title: Model Score
          description: 'Raw model score from -1 to +1: the probability of positive
            minus the probability of negative. `sentiment_score` maps it onto the
            shared scale, where ±0.14 separates positive and negative from neutral.'
          examples:
          - 0.9988
        vader_compound:
          anyOf:
          - type: number
            maximum: 1.0
            minimum: -1.0
          - type: 'null'
          title: Vader Compound
          description: Engine 5.4.1 only; since engine 5.5 it is null. VADER compound
            score after finance lexicon tuning.
          deprecated: true
        roberta_score:
          anyOf:
          - type: number
            maximum: 1.0
            minimum: -1.0
          - type: 'null'
          title: Roberta Score
          description: Engine 5.4.1 only; since engine 5.5 it is null; see `model_score`.
            RoBERTa ensemble score.
          deprecated: true
        emoji_score:
          type: number
          maximum: 1.0
          minimum: -1.0
          title: Emoji Score
          description: Engine 5.4.1 only; since engine 5.5 it is 0. Emoji-derived
            sentiment score.
          deprecated: true
          examples:
          - 0.0
        phrase_adjustment:
          type: number
          title: Phrase Adjustment
          description: Engine 5.4.1 only; since engine 5.5 it is 0. Directional finance
            phrase adjustment.
          deprecated: true
          examples:
          - 0.0
        phrase_matches:
          items:
            $ref: '#/components/schemas/SentimentPhraseMatch'
          type: array
          title: Phrase Matches
          description: Engine 5.4.1 only; since engine 5.5 it is empty. Directional
            finance phrases matched by the engine.
          deprecated: true
        contextual_finance_matches:
          items:
            type: string
          type: array
          title: Contextual Finance Matches
          description: Engine 5.4.1 only; since engine 5.5 it is empty. Contextual
            finance phrases that informed scoring.
          deprecated: true
          examples:
          - []
      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
          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:
          - google/gemma-4-31B-it-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: google/gemma-4-31B-it-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 (null if unknown)
          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:00Z'
    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: UTC timestamp of creation (ISO 8601)
          examples:
          - '2025-12-28T10:30:00Z'
      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 (null if unknown)
          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
        - limit
        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
          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. 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); null until the day is aggregated,
            while the activity fields are already filled
          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.53.4
        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: Data collection status
        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.53.4
        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.
            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 5 stocks of the selected period by buzz_score. mentions
            and sentiment_score cover every day of the period.
      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 in UTC (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 data collection is running (reported within the last
            90 minutes)
          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/Twitter data collection status.
      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.
            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: All-time number of stored X mentions
          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: Number of supported stock tickers
          default: 0
      type: object
      title: XStatsResponse
      description: X/Twitter service statistics.
      examples:
      - total_mentions: 935
        unique_tickers: 100
        mentions_today: 42
        unique_tickers_today: 12
        supported_tickers: 35000
    XStockDetailResponse:
      properties:
        ticker:
          type: string
          title: Ticker
          description: Stock ticker symbol
        company_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Name
          description: Company name
        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: Buzz score (0-100) from tweet activity, including author diversity
            (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.
            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, in the same format
        as the Reddit API.
      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.
            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.
            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
          examples:
          - Tesla, Inc.
        buzz_score:
          anyOf:
          - type: number
            maximum: 100.0
            minimum: 0.0
          - type: 'null'
          title: Buzz Score
          description: 'Buzz score from tweet activity. Components: mentions (20),
            sentiment (20), quality (10), author diversity (14) and 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.
          examples:
          - rising
        mentions:
          type: integer
          minimum: 0.0
          title: Mentions
          description: Number of tweets mentioning the ticker
          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, in the same format as the Reddit
        API.


        Metrics come from tweets and replies that mention the ticker. Author

        diversity rewards discussion spread across many accounts.'
      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.


        Get your API key at https://adanos.org/register.


        Format: `sk_live_` followed by 32 hexadecimal characters. Example: `sk_live_0123456789abcdef0123456789abcdef`.'
      in: header
      name: X-API-Key
tags:
- name: Reddit Stocks
  description: Stock discussion from posts and comments in investing subreddits. A
    reply without a ticker inherits the ticker of its thread. Start with `/trending`,
    then open `/stock/{ticker}` or track a watchlist with `/compare`.
- name: Reddit Crypto
  description: Token discussion from posts and comments in crypto subreddits. It mirrors
    Reddit Stocks, with `/token/{symbol}` in place of `/stock/{ticker}` and without
    the sector, country and AI explanation endpoints.
- name: X/Twitter Stocks
  description: Stock discussion on X/Twitter, collected from cashtag tweets and their
    replies. Likes are reported as `total_upvotes`.
- name: Polymarket Stocks
  description: Stock-related prediction markets on Polymarket. Signals come from trades,
    prices, liquidity and order books. Activity is counted in trades and markets (`trade_count`,
    `market_count`).
- name: News Stocks
  description: Stock coverage in financial news articles. `source_count` shows how
    many outlets reported. `source` filters by publisher. News identifies companies,
    so use `BRK` where other platforms take `BRK.B`.
- name: Health-Check
  description: Public status endpoints. No API key needed. Each one reports whether
    its platform is collecting data and when it last did.
- name: Finance Sentiment
  description: Scores the sentiment of financial text you send, such as a headline
    or a sentence about a company. Uses Adanos News Sentiment 5.5. Professional plan.