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

# List Watchlists

> Returns all watchlists belonging to the authenticated user, ordered by position (ascending) then creation date. Each watchlist includes a company count but not the full company list — use the Get Watchlist Details endpoint to retrieve companies. Requires the `read:watchlist` scope.



## OpenAPI

````yaml https://nordicfinancialnews.com/openapi/v1/openapi.yaml get /api/v1/watchlists
openapi: 3.0.1
info:
  title: Nordic Financial News API
  version: v1.0
  description: >
    REST API for Nordic financial news. Each article is summarized in English
    (headline, short summary, and key points) with the original-language article
    linked via `article_url`. The full article body stays at the source.


    ## Authentication

    All endpoints require Bearer token authentication using an API key.

    Include the API key in the Authorization header:

    ```

    Authorization: Bearer YOUR_API_KEY

    ```


    ## Rate Limiting

    The API enforces per-hour rate limits based on your plan:

    - **Free**: 100 requests/hour

    - **Pro**: 5,000 requests/hour


    Rate limit information is included in response headers:

    - `X-RateLimit-Limit`: Maximum requests per hour

    - `X-RateLimit-Remaining`: Requests remaining

    - `X-RateLimit-Reset`: Seconds until limit resets

    - `X-RateLimit-Policy`: Human-readable rate limit policy (e.g. `5000 per
    hour; token bucket`)


    The `/health` endpoint is exempt from rate limiting and does not return rate
    limit headers.


    ## Monthly Usage Limits

    Each API key has a monthly request allowance based on your plan:

    - **Free**: 50 requests/month

    - **Plus**: 10,000 requests/month

    - **Pro**: 50,000 requests/month


    Monthly usage information is included in response headers:

    - `X-Monthly-Limit`: Maximum requests per month

    - `X-Monthly-Remaining`: Requests remaining this month

    - `X-Monthly-Reset`: ISO 8601 timestamp when the limit resets (end of month)


    When the monthly limit is exceeded, the API returns `429 Too Many Requests`
    with a `Retry-After` header.


    ## Caching

    The API supports HTTP caching with ETags. Include the `If-None-Match`

    header with the ETag from a previous response to receive a 304 Not Modified

    response if the data hasn't changed.


    ## Pagination

    List endpoints support cursor-based pagination. Use the `cursor` parameter

    with the value from `pagination.next_cursor` in the response to fetch the
    next page.

    Paginated responses also include a `Link` header with `rel="next"` pointing
    to the next page URL.


    ## Error Handling

    Errors follow the RFC 9457 Problem Details format with appropriate HTTP
    status codes.
  contact:
    name: API Support
    email: hello@nordicfinancialnews.com
servers:
  - url: https://nordicfinancialnews.com
    description: Production server
security: []
paths:
  /api/v1/watchlists:
    get:
      tags:
        - Watchlists
      summary: List Watchlists
      description: >-
        Returns all watchlists belonging to the authenticated user, ordered by
        position (ascending) then creation date. Each watchlist includes a
        company count but not the full company list — use the Get Watchlist
        Details endpoint to retrieve companies. Requires the `read:watchlist`
        scope.
      responses:
        '200':
          description: Watchlists retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  watchlists:
                    type: array
                    items:
                      $ref: '#/components/schemas/WatchlistSummary'
                required:
                  - watchlists
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                unauthorized:
                  value:
                    type: https://docs.nordicfinancialnews.com/problems/auth-invalid
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid API key
                    instance: urn:request:abc123
              schema:
                $ref: '#/components/schemas/problem_details'
      security:
        - bearer_auth: []
components:
  schemas:
    WatchlistSummary:
      type: object
      required:
        - id
        - name
        - position
        - company_count
      properties:
        id:
          type: string
          description: Unique watchlist identifier
          example: a1b2c3d4e5f6
        name:
          type: string
          description: User-defined watchlist name
          example: Tech Stocks
        position:
          type: integer
          description: Display order (lower values appear first)
          example: 0
        company_count:
          type: integer
          description: Number of companies in the watchlist
          example: 12
        created_at:
          type: string
          format: date-time
          description: When the watchlist was created
          example: '2025-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: When the watchlist was last modified
          example: '2025-03-01T14:00:00Z'
    problem_details:
      type: object
      required:
        - type
        - title
        - status
        - detail
        - instance
      properties:
        type:
          type: string
          description: URI that identifies the problem type
        title:
          type: string
          description: Short human-readable summary
        status:
          type: integer
          description: HTTP status code
        detail:
          type: string
          description: Human-readable explanation
        instance:
          type: string
          description: URI that identifies the specific occurrence
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API Key authentication using Bearer token

````