> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byul.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch

> Retrieve the latest financial news articles with filtering and pagination support

> This endpoint supports date range filtering via `startDate` and `endDate` (ISO 8601).


## OpenAPI

````yaml GET /news
openapi: 3.1.0
info:
  title: Byul AI Financial Data API v2
  description: >-
    Real-time financial news API providing global economic news and market
    updates
  version: 2.0.0
  contact:
    name: Byul Support
    url: https://www.byul.ai/contact
  license:
    name: Proprietary
    url: https://www.byul.ai/terms
servers:
  - url: https://api.byul.ai/api/v2
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /news:
    get:
      summary: Fetch
      description: >-
        Retrieve the latest financial news articles with filtering and
        pagination support
      operationId: fetchNews
      parameters:
        - name: limit
          in: query
          description: Number of articles to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          example: 20
        - name: cursor
          in: query
          description: Pagination cursor for next page
          required: false
          schema:
            type: string
          example: 67850d7b0123456789abcde0
        - name: sinceId
          in: query
          description: Fetch articles after this ID
          required: false
          schema:
            type: string
          example: 67850d7b0123456789abcdef
        - name: minImportance
          in: query
          description: Minimum importance level
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10
            default: 1
          example: 5
        - name: q
          in: query
          description: Search query for filtering articles
          required: false
          schema:
            type: string
          example: tesla earnings
        - name: startDate
          in: query
          description: Start of date range (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
          example: '2024-01-01T00:00:00.000Z'
        - name: endDate
          in: query
          description: End of date range (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
          example: '2024-01-31T23:59:59.999Z'
        - name: symbol
          in: query
          description: Stock symbol filter
          required: false
          schema:
            type: string
          example: AAPL
      responses:
        '200':
          description: Successfully retrieved news articles
          headers:
            X-V2-RateLimit-Limit:
              description: Request limit per minute
              schema:
                type: integer
            X-V2-RateLimit-Remaining:
              description: Requests remaining in current window
              schema:
                type: integer
            X-V2-RateLimit-Used:
              description: Requests used in current window
              schema:
                type: integer
            X-V2-RateLimit-Reset:
              description: Unix timestamp when rate limit resets
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsResponse'
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - API key required or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required - Plan expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Feature not available on current plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    NewsResponse:
      type: object
      required:
        - items
        - hasMore
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/NewsArticle'
          description: Array of news articles
        nextCursor:
          type: string
          nullable: true
          description: Cursor for next page (only when hasMore is true, can be null)
          example: 67850d7b0123456789abcde0
        hasMore:
          type: boolean
          description: Whether additional pages are available
          example: true
    ErrorResponse:
      type: object
      required:
        - statusCode
        - message
        - error
        - timestamp
        - path
      properties:
        statusCode:
          type: integer
          description: HTTP status code
          example: 401
        message:
          type: string
          description: Error message
          example: >-
            API key is required. Please provide a valid V2 API key in the
            X-API-Key header.
        error:
          type: string
          description: Error type
          example: Unauthorized
        timestamp:
          type: string
          format: date-time
          description: Error timestamp
          example: '2024-01-15T10:30:00.123Z'
        path:
          type: string
          description: API endpoint path
          example: /api/v2/news
    NewsArticle:
      type: object
      required:
        - _id
        - title
        - url
        - date
        - createdAt
        - source
        - timestamp
        - importanceScore
        - category
      properties:
        _id:
          type: string
          description: Unique article ID
          example: 67850d7b0123456789abcdef
        title:
          type: string
          description: Article title (primary, usually English)
          example: Tesla Stock Surges After Q4 Earnings Beat
        koTitle:
          type: string
          description: Korean title (optional)
          example: 테슬라 4분기 실적 발표 후 주가 급등
        content:
          type: string
          description: Article content or summary (optional)
          example: >-
            Tesla Inc. reported stronger-than-expected Q4 2024 earnings, with
            revenue beating analyst estimates by 8%. The electric vehicle maker
            delivered 484,507 vehicles in Q4, up 15% year-over-year, driving
            shares up 12% in after-hours trading.
        koContent:
          type: string
          description: Korean content or summary (optional)
          example: >-
            테슬라가 2024년 4분기 실적에서 애널리스트 예상치를 8% 상회하는 매출을 기록했습니다. 이 전기차 제조업체는 4분기에
            484,507대를 인도하며 전년 대비 15% 증가했고, 시간외 거래에서 주가가 12% 상승했습니다.
        url:
          type: string
          format: uri
          description: Original article URL
          example: https://www.byul.ai/news/tesla-earnings-q4-2024
        date:
          type: string
          format: date-time
          description: Article date (ISO 8601 format)
          example: '2024-01-15T10:30:00.000Z'
        createdAt:
          type: string
          format: date-time
          description: Creation time (ISO 8601 format)
          example: '2024-01-15T10:30:00.000Z'
        source:
          type: string
          description: News source name (always 'byul.ai')
          example: byul.ai
        timestamp:
          type: integer
          description: Unix timestamp
          example: 1705401000
        importanceScore:
          type: integer
          minimum: 0
          maximum: 10
          description: Market importance (0-10, higher = more important)
          example: 8
        category:
          type: string
          description: News category
          example: earnings
        symbols:
          type: array
          items:
            type: string
          description: Related stock symbols array (optional)
          example:
            - TSLA
        sentiment:
          type: string
          enum:
            - positive
            - negative
            - neutral
          description: Sentiment analysis result (optional)
          example: positive
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key authentication. Get your API key from
        https://www.byul.ai/api/dashboard

````