openapi: 3.2.0
info:
  title: Marketaux Entities 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: Entities
  description: Entity statistics, trending entities, entity search, and entity metadata.
paths:
  /v1/entity/stats/intraday:
    get:
      operationId: getEntityStatsIntraday
      tags:
      - Entities
      summary: Entity stats (time series)
      description: Get an intraday view of how well entities performed over different intervals. Find the best or worst performing entities broken down to every minute, hour, day, week, month, quarter or year. Useful for comparing entities and creating graphs and charts. Available on Standard plans and above.
      parameters:
      - name: interval
        in: query
        description: 'The interval of the time series. Maximum time frame per interval (from the published_before date): minute = 7 days, hour = 1 month, day = 3 years, week = 5 years, month = 5 years, quarter = 10 years, year = 10 years. If the time frame is exceeded the maximum is applied without error.'
        schema:
          type: string
          enum:
          - minute
          - hour
          - day
          - week
          - month
          - quarter
          - year
          default: day
      - $ref: '#/components/parameters/groupBy'
      - $ref: '#/components/parameters/minDocCount'
      - $ref: '#/components/parameters/symbols'
      - $ref: '#/components/parameters/entityTypes'
      - $ref: '#/components/parameters/industries'
      - $ref: '#/components/parameters/countries'
      - $ref: '#/components/parameters/sentimentAvgGte'
      - $ref: '#/components/parameters/sentimentAvgLte'
      - $ref: '#/components/parameters/sentimentGte'
      - $ref: '#/components/parameters/sentimentLte'
      - $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'
      - $ref: '#/components/parameters/statsSort'
      - $ref: '#/components/parameters/statsSortOrder'
      - name: date_order
        in: query
        description: Ordering of the date keys. Default desc.
        schema:
          type: string
          enum:
          - desc
          - asc
          default: desc
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Time-series buckets of entity document counts and average sentiment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntityStatsBucket'
        '400':
          $ref: '#/components/responses/MalformedParameters'
        '401':
          $ref: '#/components/responses/InvalidApiToken'
        '402':
          $ref: '#/components/responses/UsageLimitReached'
        '403':
          $ref: '#/components/responses/EndpointAccessRestricted'
        '429':
          $ref: '#/components/responses/RateLimitReached'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/MaintenanceMode'
  /v1/entity/stats/aggregation:
    get:
      operationId: getEntityStatsAggregation
      tags:
      - Entities
      summary: Entity stats (aggregation)
      description: Similar to the entity stats time series endpoint, this returns an aggregation of entities for a single time frame rather than being broken down by date. Useful to find the best or worst performing stocks. Available on Standard plans and above.
      parameters:
      - $ref: '#/components/parameters/groupBy'
      - $ref: '#/components/parameters/minDocCount'
      - $ref: '#/components/parameters/symbols'
      - $ref: '#/components/parameters/entityTypes'
      - $ref: '#/components/parameters/industries'
      - $ref: '#/components/parameters/countries'
      - $ref: '#/components/parameters/sentimentAvgGte'
      - $ref: '#/components/parameters/sentimentAvgLte'
      - $ref: '#/components/parameters/sentimentGte'
      - $ref: '#/components/parameters/sentimentLte'
      - $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'
      - $ref: '#/components/parameters/statsSort'
      - $ref: '#/components/parameters/statsSortOrder'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Aggregated entity document counts and average sentiment for a single time frame.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/AggregationMeta'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntityAggregation'
        '400':
          $ref: '#/components/responses/MalformedParameters'
        '401':
          $ref: '#/components/responses/InvalidApiToken'
        '402':
          $ref: '#/components/responses/UsageLimitReached'
        '403':
          $ref: '#/components/responses/EndpointAccessRestricted'
        '429':
          $ref: '#/components/responses/RateLimitReached'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/MaintenanceMode'
  /v1/entity/trending/aggregation:
    get:
      operationId: getTrendingEntities
      tags:
      - Entities
      summary: Trending entities
      description: Identify trending entities. Filter by time frame and more; e.g. find which stocks were trending on a specific day, within the past 24 hours, past 7 days, etc. Available on Standard plans and above.
      parameters:
      - $ref: '#/components/parameters/groupBy'
      - $ref: '#/components/parameters/minDocCount'
      - $ref: '#/components/parameters/symbols'
      - $ref: '#/components/parameters/entityTypes'
      - $ref: '#/components/parameters/industries'
      - $ref: '#/components/parameters/countries'
      - $ref: '#/components/parameters/sentimentAvgGte'
      - $ref: '#/components/parameters/sentimentAvgLte'
      - $ref: '#/components/parameters/sentimentGte'
      - $ref: '#/components/parameters/sentimentLte'
      - $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'
      - $ref: '#/components/parameters/statsSort'
      - $ref: '#/components/parameters/statsSortOrder'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Trending entities with document counts, average sentiment, and trending score.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/AggregationMeta'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TrendingEntity'
        '400':
          $ref: '#/components/responses/MalformedParameters'
        '401':
          $ref: '#/components/responses/InvalidApiToken'
        '402':
          $ref: '#/components/responses/UsageLimitReached'
        '403':
          $ref: '#/components/responses/EndpointAccessRestricted'
        '429':
          $ref: '#/components/responses/RateLimitReached'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/MaintenanceMode'
  /v1/entity/search:
    get:
      operationId: searchEntities
      tags:
      - Entities
      summary: Entity search
      description: Search for all entities supported by Marketaux. The limit is 50 for all requests. Available on all plans.
      parameters:
      - name: search
        in: query
        description: Dynamic search function to find entities.
        schema:
          type: string
      - $ref: '#/components/parameters/symbols'
      - name: exchanges
        in: query
        description: Filter results by specific exchanges. Comma separated list.
        schema:
          type: string
      - name: types
        in: query
        description: Filter results by entity types. Comma separated list.
        schema:
          type: string
      - name: industries
        in: query
        description: Filter results by industries. Comma separated list.
        schema:
          type: string
      - name: countries
        in: query
        description: Filter results by ISO 3166-1 two-letter country code of the exchange. Comma separated list.
        schema:
          type: string
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Matching entities.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntitySearchResult'
              example:
                meta:
                  found: 1
                  returned: 1
                  limit: 50
                  page: 1
                data:
                - symbol: TSLA
                  name: Tesla, Inc.
                  type: equity
                  industry: Consumer Cyclical
                  exchange: null
                  exchange_long: null
                  country: us
        '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/entity/type/list:
    get:
      operationId: listEntityTypes
      tags:
      - Entities
      summary: Entity type list
      description: Return all supported entity types. Available on all plans.
      responses:
        '200':
          description: Supported entity types.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: string
              example:
                data:
                - equity
                - index
                - etf
                - mutualfund
                - currency
                - cryptocurrency
        '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/entity/industry/list:
    get:
      operationId: listEntityIndustries
      tags:
      - Entities
      summary: Industry list
      description: Return all supported entity industries. Available on all plans.
      responses:
        '200':
          description: Supported entity industries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: string
              example:
                data:
                - Technology
                - Industrials
                - N/A
                - Consumer Cyclical
                - Healthcare
                - Communication Services
                - Financial Services
                - Consumer Defensive
                - Basic Materials
                - Real Estate
                - Energy
                - Utilities
                - Financial
                - Services
                - Consumer Goods
                - Industrial Goods
        '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'
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
    statsSort:
      name: sort
      in: query
      description: Sort by total_documents or sentiment_avg. Default total_documents.
      schema:
        type: string
        enum:
        - total_documents
        - sentiment_avg
        default: total_documents
    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
    groupBy:
      name: group_by
      in: query
      description: Group results by symbol, exchange, industry or country. Default symbol.
      schema:
        type: string
        enum:
        - symbol
        - exchange
        - industry
        - country
        default: symbol
    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
    sentimentAvgGte:
      name: sentiment_avg_gte
      in: query
      description: Refine results to entities with an overall sentiment_avg greater 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
    statsSortOrder:
      name: sort_order
      in: query
      description: Sort order of the sort parameter. Default desc.
      schema:
        type: string
        enum:
        - desc
        - asc
        default: desc
    minDocCount:
      name: min_doc_count
      in: query
      description: The minimum number of total_documents an entity should be identified within to be returned with the results.
      schema:
        type: integer
    excludeSourceIds:
      name: exclude_source_ids
      in: query
      description: Comma separated list of source_ids to exclude.
      schema:
        type: string
    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
    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
    sentimentAvgLte:
      name: sentiment_avg_lte
      in: query
      description: Refine results to entities with an overall sentiment_avg less than or equal to x.
      schema:
        type: number
        minimum: -1
        maximum: 1
    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'
    EndpointAccessRestricted:
      description: 'endpoint_access_restricted: Access to the endpoint is not available on your current subscription plan.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    EntitySearchResult:
      type: object
      description: An entity supported by Marketaux.
      properties:
        symbol:
          type: string
          description: Unique entity symbol (or ticker).
        name:
          type: string
          description: Entity name.
        type:
          type: string
          description: The entity type.
        industry:
          type: string
          description: The entity industry.
        exchange:
          type:
          - string
          - 'null'
          description: The exchange identifier.
        exchange_long:
          type:
          - string
          - 'null'
          description: The exchange name.
        country:
          type: string
          description: The ISO 3166-1 two-letter country code of the exchange locale ('eu' and 'global' are also included).
    AggregationMeta:
      type: object
      description: Metadata returned on aggregation endpoints.
      properties:
        returned:
          type: integer
          description: The number of entities returned.
        limit:
          type: integer
          description: The limit based on the limit parameter.
    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.
    TrendingEntity:
      allOf:
      - $ref: '#/components/schemas/EntityAggregation'
      - type: object
        properties:
          score:
            type: number
            description: The relevance score for the trending entity.
      example:
        key: NVDA
        total_documents: 22
        sentiment_avg: 0.436025815253908
        score: 3.7920454395721324
    EntityAggregation:
      type: object
      description: Aggregated document count and sentiment for a grouped key.
      properties:
        key:
          type: string
          description: The key based on the group_by parameter (symbol, exchange, industry or country).
        total_documents:
          type: integer
          description: Total number of documents identified for the key based on the query parameters.
        sentiment_avg:
          type:
          - number
          - 'null'
          description: Average sentiment of the key based on the query parameters.
      example:
        key: TSLA
        total_documents: 14
        sentiment_avg: 0.388841356283852
    EntityStatsBucket:
      type: object
      description: One time-series bucket of entity statistics.
      properties:
        date:
          type: string
          description: Date of the time series data.
        data:
          type: array
          items:
            $ref: '#/components/schemas/EntityAggregation'
      example:
        date: '2024-11-10T00:00:00.000Z'
        data:
        - key: TSLA
          total_documents: 14
          sentiment_avg: 0.388841356283852
    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.