openapi: 3.2.0
info:
  title: Marketaux News API
  description: Global financial and stock market news API. Generate news feeds filtered by entity symbol, type, exchange, industry, country and more, with per-entity sentiment and match scores. Covers 5,000+ news sources globally in 30+ languages, tracking 200,000+ entities across 80+ markets. Also provides entity statistics (time series and aggregations) and trending-entity endpoints for charting the best and worst performing entities in the news.
  version: v1
  termsOfService: https://www.marketaux.com/tos
  contact:
    url: https://www.marketaux.com/contact
servers:
- url: https://api.marketaux.com
security:
- apiToken: []
tags:
- name: News
  description: Financial and market news feeds, similar-article lookup, and article retrieval by UUID.
paths:
  /v1/news/all:
    get:
      operationId: getAllNews
      tags:
      - News
      summary: Finance and market news
      description: Get all the latest global financial news and filter by entities identified within articles to build concise news feeds. Also provided is analysis of each entity identified in articles. Not every article may have entities identified; use must_have_entities or entity parameters such as symbols or exchanges for more concise results. Available on all plans.
      parameters:
      - $ref: '#/components/parameters/symbols'
      - $ref: '#/components/parameters/entityTypes'
      - $ref: '#/components/parameters/industries'
      - $ref: '#/components/parameters/countries'
      - $ref: '#/components/parameters/sentimentGte'
      - $ref: '#/components/parameters/sentimentLte'
      - name: min_match_score
        in: query
        description: Find all articles with entities with a match_score greater than or equal to min_match_score.
        schema:
          type: number
      - $ref: '#/components/parameters/filterEntities'
      - $ref: '#/components/parameters/mustHaveEntities'
      - $ref: '#/components/parameters/groupSimilar'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/domains'
      - $ref: '#/components/parameters/excludeDomains'
      - $ref: '#/components/parameters/sourceIds'
      - $ref: '#/components/parameters/excludeSourceIds'
      - $ref: '#/components/parameters/language'
      - $ref: '#/components/parameters/publishedBefore'
      - $ref: '#/components/parameters/publishedAfter'
      - $ref: '#/components/parameters/publishedOn'
      - name: sort
        in: query
        description: Sort by published_on, entity_match_score, entity_sentiment_score or relevance_score (relevance_score only available when used in conjunction with search). Default is published_at unless search is used, in which case relevance_score is used.
        schema:
          type: string
          enum:
          - published_on
          - entity_match_score
          - entity_sentiment_score
          - relevance_score
      - name: sort_order
        in: query
        description: Sort order of the sort parameter. Can only be used with sort = entity_match_score or entity_sentiment_score. Default desc.
        schema:
          type: string
          enum:
          - desc
          - asc
          default: desc
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: News articles matching the query, with identified entities and sentiment analysis.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewsArticle'
        '400':
          $ref: '#/components/responses/MalformedParameters'
        '401':
          $ref: '#/components/responses/InvalidApiToken'
        '402':
          $ref: '#/components/responses/UsageLimitReached'
        '429':
          $ref: '#/components/responses/RateLimitReached'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/MaintenanceMode'
  /v1/news/similar/{uuid}:
    get:
      operationId: getSimilarNews
      tags:
      - News
      summary: Similar news
      description: Find similar stories to a specific article based on its UUID. Available on all plans.
      parameters:
      - $ref: '#/components/parameters/uuidPath'
      - $ref: '#/components/parameters/symbols'
      - $ref: '#/components/parameters/entityTypes'
      - $ref: '#/components/parameters/industries'
      - $ref: '#/components/parameters/countries'
      - $ref: '#/components/parameters/sentimentGte'
      - $ref: '#/components/parameters/sentimentLte'
      - $ref: '#/components/parameters/filterEntities'
      - $ref: '#/components/parameters/mustHaveEntities'
      - $ref: '#/components/parameters/groupSimilar'
      - $ref: '#/components/parameters/domains'
      - $ref: '#/components/parameters/excludeDomains'
      - $ref: '#/components/parameters/sourceIds'
      - $ref: '#/components/parameters/excludeSourceIds'
      - $ref: '#/components/parameters/language'
      - $ref: '#/components/parameters/publishedBefore'
      - $ref: '#/components/parameters/publishedAfter'
      - $ref: '#/components/parameters/publishedOn'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Articles similar to the referenced article, ranked by relevance_score.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewsArticle'
        '400':
          $ref: '#/components/responses/MalformedParameters'
        '401':
          $ref: '#/components/responses/InvalidApiToken'
        '402':
          $ref: '#/components/responses/UsageLimitReached'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '429':
          $ref: '#/components/responses/RateLimitReached'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/MaintenanceMode'
  /v1/news/uuid/{uuid}:
    get:
      operationId: getNewsByUuid
      tags:
      - News
      summary: News by UUID
      description: Find a specific article by the UUID returned by the search endpoints. Useful for storing the UUID and returning the article later. Available on all plans.
      parameters:
      - $ref: '#/components/parameters/uuidPath'
      responses:
        '200':
          description: The requested news article.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsArticle'
        '401':
          $ref: '#/components/responses/InvalidApiToken'
        '402':
          $ref: '#/components/responses/UsageLimitReached'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '429':
          $ref: '#/components/responses/RateLimitReached'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/MaintenanceMode'
components:
  parameters:
    entityTypes:
      name: entity_types
      in: query
      description: 'Specify the type of entities identified within the article. Comma separated. Example: entity_types=index,equity'
      schema:
        type: string
    publishedBefore:
      name: published_before
      in: query
      description: 'Find all articles published before the specified date. Supported formats: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y. All dates are UTC.'
      schema:
        type: string
    search:
      name: search
      in: query
      description: 'Full-text search over article body and title. Supports advanced query syntax: + (AND), | (OR), - (negate), quotes (phrase), * (prefix), parentheses (precedence); escape literals with a backslash. Example: "ipo" -nyse'
      schema:
        type: string
    excludeDomains:
      name: exclude_domains
      in: query
      description: Comma separated list of domains to exclude.
      schema:
        type: string
    sentimentLte:
      name: sentiment_lte
      in: query
      description: Find all articles with entities with a sentiment_score less than or equal to x.
      schema:
        type: number
        minimum: -1
        maximum: 1
    industries:
      name: industries
      in: query
      description: 'Specify the industries of entities identified within the article. Comma separated. Example: industries=Technology,Industrials'
      schema:
        type: string
    publishedAfter:
      name: published_after
      in: query
      description: 'Find all articles published after the specified date. Supported formats: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y. All dates are UTC.'
      schema:
        type: string
    domains:
      name: domains
      in: query
      description: 'Comma separated list of domains to include. Obtain domains from the sources endpoint. Example: adweek.com,adage.com'
      schema:
        type: string
    sourceIds:
      name: source_ids
      in: query
      description: 'Comma separated list of source_ids to include. Obtain source_ids from the sources endpoint. Example: adweek.com-1,adage.com-1'
      schema:
        type: string
    language:
      name: language
      in: query
      description: 'Comma separated list of languages to include (e.g. en,es). Default is all. Supported languages: ar, bg, bn, cs, da, de, el, en, es, et, fa, fi, fr, he, hi, hr, hu, id, it, ja, ko, lt, multi, nl, no, pl, pt, ro, ru, sk, sv, ta, th, tr, uk, vi, zh.'
      schema:
        type: string
    uuidPath:
      name: uuid
      in: path
      required: true
      description: The unique identifier (UUID) for an article, as returned by the search endpoints.
      schema:
        type: string
        format: uuid
    mustHaveEntities:
      name: must_have_entities
      in: query
      description: Set to true to ensure that at least one entity has been identified within the article. Default false.
      schema:
        type: boolean
        default: false
    excludeSourceIds:
      name: exclude_source_ids
      in: query
      description: Comma separated list of source_ids to exclude.
      schema:
        type: string
    groupSimilar:
      name: group_similar
      in: query
      description: Group similar articles to avoid displaying multiple articles on the same topic/subject. Default true.
      schema:
        type: boolean
        default: true
    countries:
      name: countries
      in: query
      description: 'Specify the country of the exchange of which entities have been identified within the article. Comma separated. Example: countries=us,ca'
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: Number of results to return. The maximum limit is based on your plan; the default limit is the maximum specified for your plan.
      schema:
        type: integer
    publishedOn:
      name: published_on
      in: query
      description: 'Find all articles published on the specified date. Supported format: Y-m-d.'
      schema:
        type: string
    sentimentGte:
      name: sentiment_gte
      in: query
      description: Find all articles with entities with a sentiment_score greater than or equal to x. Sentiment is between -1 and +1; 0 = neutral, above 0 = positive, below 0 = negative.
      schema:
        type: number
        minimum: -1
        maximum: 1
    filterEntities:
      name: filter_entities
      in: query
      description: By default all entities for each article are returned; set to true to return only the entities relevant to your query with each article. Default false.
      schema:
        type: boolean
        default: false
    symbols:
      name: symbols
      in: query
      description: 'Specify entity symbol(s) which have been identified within the article. Comma separated. Example: symbols=TSLA,AMZN,MSFT'
      schema:
        type: string
    page:
      name: page
      in: query
      description: Paginate through the result set. Default 1. The max result set cannot exceed 20,000 (e.g. with limit 50 the max page is 400).
      schema:
        type: integer
        default: 1
  responses:
    UsageLimitReached:
      description: 'usage_limit_reached: Usage limit of your plan has been reached. Usage limit and remaining requests can be found on the X-UsageLimit-Limit header.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidApiToken:
      description: 'invalid_api_token: Invalid API token.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_api_token
              message: An invalid API token was supplied.
    MalformedParameters:
      description: 'malformed_parameters: Validation of parameters failed. The failed parameters are usually shown in the error message.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MaintenanceMode:
      description: 'maintenance_mode: The service is currently under maintenance.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimitReached:
      description: 'rate_limit_reached: Too many requests in the past 60 seconds. Rate limit and remaining requests can be found on the X-RateLimit-Limit header.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: 'server_error: A server error occurred.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ResourceNotFound:
      description: 'resource_not_found: Resource could not be found (also invalid_api_endpoint when the API route does not exist).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Highlight:
      type: object
      description: A snippet of article text where an entity was identified.
      properties:
        highlight:
          type: string
          description: Snippet of text from the article where the entity has been identified.
        sentiment:
          type: number
          description: The sentiment of the highlighted text.
        highlighted_in:
          type: string
          enum:
          - title
          - main_text
          description: Where the highlight was found.
    NewsArticle:
      type: object
      description: A news article with identified entities and sentiment analysis.
      properties:
        uuid:
          type: string
          description: The unique identifier for an article in the Marketaux system.
        title:
          type: string
          description: The article title.
        description:
          type: string
          description: The article meta description.
        keywords:
          type: string
          description: The article meta keywords.
        snippet:
          type: string
          description: A short snippet of the article body.
        url:
          type: string
          description: The URL to the article.
        image_url:
          type: string
          description: The URL to the article image.
        language:
          type: string
          description: The language of the source.
        published_at:
          type: string
          description: The datetime the article was published (UTC).
        source:
          type: string
          description: The domain of the source.
        relevance_score:
          type:
          - number
          - 'null'
          description: Relevance score based on the search parameter; null when the search parameter is not used.
        entities:
          type: array
          items:
            $ref: '#/components/schemas/Entity'
        similar:
          type: array
          description: Array of news articles which are very similar to the main article.
          items:
            $ref: '#/components/schemas/NewsArticle'
      example:
        uuid: 70cb577e-c2dd-4dde-b501-f713823a4939
        title: Trump wins 2024, markets surge globally
        description: Global markets experience a significant surge following Trump's victory in the 2024 election.
        keywords: ''
        snippet: Donald Trump has won the 2024 presidential election...
        url: https://www.killerstartups.com/trump-wins-2024-markets-surge-globally/
        image_url: https://images.killerstartups.com/wp-content/uploads/2024/11/Trump-Wins.jpg
        language: en
        published_at: '2024-11-08T01:24:00.000000Z'
        source: killerstartups.com
        relevance_score: null
        entities:
        - symbol: TSLA
          name: Tesla, Inc.
          exchange: null
          exchange_long: null
          country: us
          type: equity
          industry: Consumer Cyclical
          match_score: 12.133104
          sentiment_score: 0.7783
          highlights:
          - highlight: ., majority-owned by Trump, and Tesl[+253 characters]
            sentiment: 0.7783
            highlighted_in: main_text
        similar: []
    PaginationMeta:
      type: object
      description: Pagination metadata returned on list endpoints.
      properties:
        found:
          type: integer
          description: The number of results found for the request.
        returned:
          type: integer
          description: The number of results returned on the page. If lower than limit, there are no more results after this page.
        limit:
          type: integer
          description: The limit based on the limit parameter.
        page:
          type: integer
          description: The page number based on the page parameter.
    Entity:
      type: object
      description: An entity identified within an article, with match and sentiment scores.
      properties:
        symbol:
          type: string
          description: Symbol of the identified entity.
        name:
          type: string
          description: Name of the identified entity.
        exchange:
          type:
          - string
          - 'null'
          description: Exchange identifier of the identified entity.
        exchange_long:
          type:
          - string
          - 'null'
          description: Exchange name of the identified entity.
        country:
          type: string
          description: Exchange country of the identified entity.
        type:
          type: string
          description: Type of the identified entity (equity, index, etf, mutualfund, currency, cryptocurrency).
        industry:
          type: string
          description: Industry of the identified entity.
        match_score:
          type: number
          description: The overall strength of the matching for the identified entity.
        sentiment_score:
          type: number
          description: Average sentiment of all highlighted text found for the identified entity.
        highlights:
          type: array
          items:
            $ref: '#/components/schemas/Highlight'
    Error:
      type: object
      description: Marketaux error envelope.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable error message.
      example:
        error:
          code: malformed_parameters
          message: The published_before parameter(s) are incorrectly formatted.
  securitySchemes:
    apiToken:
      type: apiKey
      in: query
      name: api_token
      description: Your API token, found on your account dashboard after signing up at https://www.marketaux.com/register. Passed as a GET parameter on every request.
externalDocs:
  description: Marketaux API documentation
  url: https://www.marketaux.com/documentation
x-provenance:
  generated: '2026-07-22'
  method: generated
  source: https://www.marketaux.com/documentation
  note: Marketaux publishes no machine-readable API definition (probes of www.marketaux.com and api.marketaux.com for /openapi.json, /openapi.yaml, /swagger.json, /v1/openapi.json and /api-docs all returned 404 on 2026-07-22). This OpenAPI was generated faithfully from the published HTML API documentation; every path, parameter, response field, and error code below is documented at the source URL. Example values are taken verbatim from the documentation.