DataForSEO ContentAnalysis API

openapi: 3.0.1
info:
  title: DataForSEO AiOptimization ContentAnalysis API
  description: DataForSEO API is the starting point on your journey towards building powerful SEO software. With DataForSEO you can get all the data you need to build an efficient application while also saving your time and budget. DataForSEO API is using the REST technology for interchanging data between your application and our service. The data exchange is made through the widely used HTTP protocol, which allows applying our API to almost all programming languages.
  version: 1.0.0
servers:
- url: https://api.dataforseo.com
- url: https://sandbox.dataforseo.com
tags:
- name: ContentAnalysis
paths:
  /v3/content_analysis/id_list:
    post:
      tags:
      - ContentAnalysis
      description: 'This endpoint is designed to provide you with a list of IDs and metadata for all Content Analysis tasks created within the specified time period, including both successful and uncompleted tasks.

        for more info please visit ''https://docs.dataforseo.com/v3/content_analysis/id_list/?bash'''
      operationId: ContentAnalysisIdList
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisIdListRequestInfo'
                nullable: true
              example:
              - datetime_from: '2026-04-12 04:39:39 +00:00'
                datetime_to: '2026-04-14 04:39:39 +00:00'
                limit: 100
                offset: 0
                sort: desc
                include_metadata: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisIdListResponseInfo'
                nullable: true
      security:
      - basicAuth: []
  /v3/content_analysis/available_filters:
    get:
      tags:
      - ContentAnalysis
      description: 'Here you will find all the necessary information about filters that can be used with Content Analysis API endpoints.

        for more info please visit ''https://docs.dataforseo.com/v3/content_analysis/filters/?bash'''
      operationId: ContentAnalysisAvailableFilters
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisAvailableFiltersResponseInfo'
                nullable: true
      security:
      - basicAuth: []
  /v3/content_analysis/locations:
    get:
      tags:
      - ContentAnalysis
      description: 'You will receive the list of locations by this API call.

        for more info please visit ''https://docs.dataforseo.com/v3/content_analysis/locations/?bash'''
      operationId: Locations
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisLocationsResponseInfo'
                nullable: true
      security:
      - basicAuth: []
  /v3/content_analysis/languages:
    get:
      tags:
      - ContentAnalysis
      description: 'You will receive the list of languages by calling this API.

         

        As a response of the API server, you will receive JSON-encoded data containing a tasks array with the information specific to the set tasks.

        for more info please visit ''https://docs.dataforseo.com/v3/content_analysis/languages/?bash'''
      operationId: Languages
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisLanguagesResponseInfo'
                nullable: true
      security:
      - basicAuth: []
  /v3/content_analysis/categories:
    get:
      tags:
      - ContentAnalysis
      description: 'We use Google product and service categories. This endpoint will provide you with the full list of available categories.

        You can also download the CSV file by this link.

        for more info please visit ''https://docs.dataforseo.com/v3/content_analysis/categories/?bash'''
      operationId: ContentAnalysisCategories
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisCategoriesResponseInfo'
                nullable: true
      security:
      - basicAuth: []
  /v3/content_analysis/search/live:
    post:
      tags:
      - ContentAnalysis
      description: 'This endpoint will provide you with detailed citation data available for the target keyword.

        for more info please visit ''https://docs.dataforseo.com/v3/content_analysis/search/live/?bash'''
      operationId: SearchLive
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisSearchLiveRequestInfo'
                nullable: true
              example:
              - keyword_fields:
                  snippet: logitech
                keyword: logitech
                page_type:
                - ecommerce
                - news
                - blogs
                - message-boards
                - organization
                search_mode: as_is
                filters:
                - main_domain
                - '='
                - reviewfinder.ca
                order_by:
                - content_info.sentiment_connotations.anger,desc
                limit: 10
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisSearchLiveResponseInfo'
                nullable: true
      security:
      - basicAuth: []
  /v3/content_analysis/summary/live:
    post:
      tags:
      - ContentAnalysis
      description: 'This endpoint will provide you with an overview of citation data available for the target keyword.

        for more info please visit ''https://docs.dataforseo.com/v3/content_analysis/summary/live/?bash'''
      operationId: ContentAnalysisSummaryLive
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisSummaryLiveRequestInfo'
                nullable: true
              example:
              - keyword: logitech
                page_type:
                - ecommerce
                - news
                - blogs
                - message-boards
                - organization
                internal_list_limit: 8
                positive_connotation_threshold: 0.5
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisSummaryLiveResponseInfo'
                nullable: true
      security:
      - basicAuth: []
  /v3/content_analysis/sentiment_analysis/live:
    post:
      tags:
      - ContentAnalysis
      description: 'This endpoint will provide you with sentiment analysis data for the citations available for the target keyword.

        for more info please visit ''https://docs.dataforseo.com/v3/content_analysis/sentiment_analysis/live/?bash'''
      operationId: SentimentAnalysisLive
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisSentimentAnalysisLiveRequestInfo'
                nullable: true
              example:
              - keyword: logitech
                internal_list_limit: 1
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisSentimentAnalysisLiveResponseInfo'
                nullable: true
      security:
      - basicAuth: []
  /v3/content_analysis/rating_distribution/live:
    post:
      tags:
      - ContentAnalysis
      description: 'This endpoint will provide you with rating distribution data for the keyword and other parameters specified in the request.

        for more info please visit ''https://docs.dataforseo.com/v3/content_analysis/rating_distribution/live/?bash'''
      operationId: RatingDistributionLive
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisRatingDistributionLiveRequestInfo'
                nullable: true
              example:
              - keyword: logitech
                search_mode: as_is
                internal_list_limit: 10
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisRatingDistributionLiveResponseInfo'
                nullable: true
      security:
      - basicAuth: []
  /v3/content_analysis/phrase_trends/live:
    post:
      tags:
      - ContentAnalysis
      description: 'This endpoint will provide you with data on all citations of the target keyword for the indicated date range.

        for more info please visit ''https://docs.dataforseo.com/v3/content_analysis/phrase_trends/live/?bash'''
      operationId: PhraseTrendsLive
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisPhraseTrendsLiveRequestInfo'
                nullable: true
              example:
              - keyword: logitech
                search_mode: as_is
                date_from: '2026-01-15'
                date_group: month
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisPhraseTrendsLiveResponseInfo'
                nullable: true
      security:
      - basicAuth: []
  /v3/content_analysis/category_trends/live:
    post:
      tags:
      - ContentAnalysis
      description: 'This endpoint will provide you with data on all citations in the target category for the indicated date range.

        for more info please visit ''https://docs.dataforseo.com/v3/content_analysis/category_trends/live/?bash'''
      operationId: CategoryTrendsLive
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisCategoryTrendsLiveRequestInfo'
                nullable: true
              example:
              - category_code: 10994
                search_mode: as_is
                date_from: '2026-01-15'
                date_group: month
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                oneOf:
                - $ref: '#/components/schemas/ContentAnalysisCategoryTrendsLiveResponseInfo'
                nullable: true
      security:
      - basicAuth: []
components:
  schemas:
    BaseResponseTaskInfo:
      properties:
        id:
          type: string
          description: 'task identifier

            unique task identifier in our system in the UUID format'
          nullable: true
        status_code:
          type: integer
          description: 'status code of the task

            generated by DataForSEO, can be within the following range: 10000-60000

            you can find the full list of the response codes here'
          nullable: true
        status_message:
          type: string
          description: 'informational message of the task

            you can find the full list of general informational messages here'
          nullable: true
        time:
          type: string
          description: execution time, seconds
          nullable: true
        cost:
          type: number
          description: total tasks cost, USD
          format: double
          nullable: true
        result_count:
          type: integer
          description: number of elements in the result array
          format: int64
          nullable: true
        path:
          type: array
          items:
            type: string
            nullable: true
          description: URL path
          nullable: true
        data:
          type: object
          additionalProperties:
            type: object
            nullable: true
          description: contains the same parameters that you specified in the POST request
          nullable: true
    ContentAnalysisSearchLiveItem:
      type: object
      properties:
        type:
          type: string
          description: type of element
          nullable: true
        url:
          type: string
          description: URL where the citation was found
          nullable: true
        domain:
          type: string
          description: domain name
          nullable: true
        main_domain:
          type: string
          description: main domain
          nullable: true
        url_rank:
          type: integer
          description: 'rank of the url

            this value is based on backlink data for the given URL from DataForSEO Backlink Index;

            url_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm

            learn more about the metric and how it is calculated in this help center article'
          nullable: true
        spam_score:
          type: integer
          description: 'backlink spam score of the url

            this value is based on backlink data for the given URL from DataForSEO Backlink Index;

            learn more about how the metric is calculated on this help center page'
          nullable: true
        domain_rank:
          type: integer
          description: 'rank of the domain

            this value is based on backlink data for the given domain from DataForSEO Backlink Index;

            domain_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm

            learn more about the metric and how it is calculated in this help center article'
          nullable: true
        fetch_time:
          type: string
          description: 'date and time when our crawler visited the page

            in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”

            example:

            2017-01-24 13:20:59 +00:00'
          nullable: true
        country:
          type: string
          description: 'country code of the domain registration

            to obtain a full list of available countries, refer to the Locations endpoint'
          nullable: true
        language:
          type: string
          description: 'main language of the domain

            to obtain a full list of available languages, refer to the Languages endpoint'
          nullable: true
        score:
          type: number
          description: 'citation prominence score

            this value is based on url_rank, domain_rank, keyword presence in title, main_title, url, snippet

            the higher the score, the more value the related citation has'
          nullable: true
        page_category:
          type: array
          items:
            type: integer
          description: 'contains all relevant page categories

            product and service categories relevant for the page

            to obtain a full list of available categories, refer to the Categories endpoint'
          nullable: true
        page_types:
          type: array
          items:
            type: string
          description: page types
          nullable: true
        ratings:
          type: array
          items:
            type: object
            oneOf:
            - $ref: '#/components/schemas/ContentRatingInfo'
            nullable: true
          description: 'ratings found on the page

            all ratings found on the page based on microdata'
          nullable: true
        social_metrics:
          type: array
          items:
            type: object
            oneOf:
            - $ref: '#/components/schemas/SocialMetricsInfo'
            nullable: true
          description: 'social media engagement metrics

            data on social media interactions associated with the content based on website embeds developed and supported by social media platforms'
          nullable: true
        content_info:
          type: object
          oneOf:
          - $ref: '#/components/schemas/AnalysisContentInfo'
          description: contains data on citations from the given url
          nullable: true
    ContentAnalysisAvailableFiltersResponseInfo:
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseResponseInfo'
      - type: object
        properties:
          tasks:
            type: array
            items:
              type: object
              oneOf:
              - $ref: '#/components/schemas/ContentAnalysisAvailableFiltersTaskInfo'
              nullable: true
            nullable: true
    ContentAnalysisPhraseTrendsLiveResponseInfo:
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseResponseInfo'
      - type: object
        properties:
          tasks:
            type: array
            items:
              type: object
              oneOf:
              - $ref: '#/components/schemas/ContentAnalysisPhraseTrendsLiveTaskInfo'
              nullable: true
            description: array of tasks
            nullable: true
    ContentAnalysisPhraseTrendsLiveResultInfo:
      type: object
      properties:
        type:
          type: string
          description: type of element
          nullable: true
        date:
          type: string
          description: date for which the data is provided
          nullable: true
        total_count:
          type: integer
          description: total number of results in our database relevant to your request
          format: int64
          nullable: true
        rank:
          type: integer
          description: 'rank of all URLs citing the keyword

            normalized sum of ranks of all URLs citing the target keyword for the given date'
          nullable: true
        top_domains:
          type: array
          items:
            type: object
            oneOf:
            - $ref: '#/components/schemas/TopDomainInfo'
            nullable: true
          description: 'top domains citing the target keyword

            contains objects with top domains citing the target keyword and citation count per each domain'
          nullable: true
        sentiment_connotations:
          type: object
          additionalProperties:
            type: integer
            format: int64
            nullable: true
          description: 'sentiment connotations

            contains sentiments (emotional reactions) related to the target keyword citation and the number of citations per each sentiment

            possible connotations: "anger", "happiness", "love", "sadness", "share", "fun"'
          nullable: true
        connotation_types:
          type: object
          additionalProperties:
            type: integer
            format: int64
            nullable: true
          description: 'connotation types

            contains types of sentiments (sentiment polarity) related to the keyword citation and citation count per each sentiment type

            possible connotation types: "positive", "negative", "neutral"'
          nullable: true
        text_categories:
          type: array
          items:
            type: object
            oneOf:
            - $ref: '#/components/schemas/ContentAnalysisCategoriesInfo'
            nullable: true
          description: 'text categories

            contains objects with text categories and citation count in each text category

            to obtain a full list of available categories, refer to the Categories endpoint'
          nullable: true
        page_categories:
          type: array
          items:
            type: object
            oneOf:
            - $ref: '#/components/schemas/ContentAnalysisCategoriesInfo'
            nullable: true
          description: 'page categories

            contains objects with page categories and citation count in each page category

            to obtain a full list of available categories, refer to the Categories endpoint'
          nullable: true
        page_types:
          type: object
          additionalProperties:
            type: integer
            format: int64
            nullable: true
          description: 'page types

            contains page types and citation count per each page type'
          nullable: true
        countries:
          type: object
          additionalProperties:
            type: integer
            format: int64
            nullable: true
          description: 'countries

            contains countries and citation count in each country

            to obtain a full list of available countries, refer to the Locations endpoint'
          nullable: true
        languages:
          type: object
          additionalProperties:
            type: integer
            format: int64
            nullable: true
          description: 'languages

            contains languages and citation count in each language

            to obtain a full list of available languages, refer to the Languages endpoint'
          nullable: true
    ContentAnalysisSentimentAnalysisLiveResultInfo:
      type: object
      properties:
        type:
          type: string
          description: type of element
          nullable: true
        positive_connotation_distribution:
          type: object
          oneOf:
          - $ref: '#/components/schemas/PositiveConnotationDistribution'
          description: 'citation distribution by sentiment connotation types

            contains objects with citation counts and relevant data distributed by types of sentiments (sentiment polarity);

            possible sentiment connotation types: positive, negative, neutral'
          nullable: true
        sentiment_connotation_distribution:
          type: object
          oneOf:
          - $ref: '#/components/schemas/SentimentConnotationDistribution'
          description: 'citation distribution by sentiment connotations

            contains objects with citation counts and relevant data distributed by sentiments (emotional reactions);

            possible sentiment connotation types: anger, happiness, love, sadness, share, fun'
          nullable: true
    ContentAnalysisRatingDistributionLiveTaskInfo:
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseResponseTaskInfo'
      - type: object
        properties:
          result:
            type: array
            items:
              type: object
              oneOf:
              - $ref: '#/components/schemas/ContentAnalysisRatingDistributionLiveResultInfo'
              nullable: true
            description: array of results
            nullable: true
    ContentAnalysisSearchLiveRequestInfo:
      type: object
      properties:
        keyword:
          type: string
          description: 'target keyword

            required field

            UTF-8 encoding

            the keywords will be converted to a lowercase format;

            Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;

            example:

            "keyword": "\"tesla palo alto\""

            learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article'
        keyword_fields:
          type: object
          additionalProperties:
            type: string
            nullable: true
          description: "target keyword fields and target keywords\noptional field\nuse this parameter to filter the dataset by keywords that certain fields should contain;\nfields you can specify: title, main_title, previous_title, snippet\nyou can indicate several fields;\nNote: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;\nexample:\n\"keyword_fields\": {\n    \"snippet\": \"\\\"logitech mouse\\\"\",\n    \"main_title\": \"sale\"\n}"
          nullable: true
        page_type:
          type: array
          items:
            type: string
          description: 'target page types

            optional field

            use this parameter to filter the dataset by page types

            possible values:

            "ecommerce", "news", "blogs", "message-boards", "organization"'
          nullable: true
        search_mode:
          type: string
          description: 'results grouping type

            optional field

            possible grouping types:

            as_is – returns all citations for the target keyword

            one_per_domain – returns one citation of the keyword per domain

            default value: as_is'
          nullable: true
        limit:
          type: integer
          description: 'the maximum number of returned citations

            optional field

            default value: 100

            maximum value: 1000'
          nullable: true
        filters:
          type: array
          items:
            type: object
            nullable: true
          description: 'array of results filtering parameters

            optional field

            you can add several filters at once (8 filters maximum)

            you should set a logical operator and, or between the conditions

            the following operators are supported:

            regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like,not_like, match, not_match

            you can use the % operator with like and not_like to match any string of zero or more characters

            example:

            ["country","=", "US"]

            [["domain_rank",">",800],"and",["content_info.connotation_types.negative",">",0.9]]

            [["domain_rank",">",800],

            "and",

            [["page_types","has","ecommerce"],

            "or",

            ["content_info.text_category","has",10994]]]

            for more information about filters, please refer to Content Analysis API – Filters'
          nullable: true
        order_by:
          type: array
          items:
            type: string
          description: 'results sorting rules

            optional field

            you can use the same values as in the filters array to sort the results

            possible sorting types:

            asc – results will be sorted in the ascending order

            desc – results will be sorted in the descending order

            you should use a comma to set up a sorting type

            example:

            ["content_info.sentiment_connotations.anger,desc"]

            default rule:

            ["content_info.sentiment_connotations.anger,desc"]

            note that you can set no more than three sorting rules in a single request

            you should use a comma to separate several sorting rules

            example:

            ["content_info.sentiment_connotations.anger,desc","keyword_data.keyword_info.cpc,desc"]'
          nullable: true
        offset:
          type: integer
          description: 'offset in the results array of returned citations

            optional field

            default value: 0

            if you specify the 10 value, the first ten citations in the results array will be omitted and the data will be provided for the successive citations

            Note: we recommend using this parameter only when retrieving up to 10,000 results

            for retrieving over 10,000 results, use the offset_token instead.'
          nullable: true
        offset_token:
          type: string
          description: 'offset token for subsequent requests

            optional field

            provided in the identical field of the response to each request;

            use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;

            by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;

            offset_token values are unique for each subsequent task

            Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task

            learn more about this parameter on our Help Center'
          nullable: true
        rank_scale:
          type: string
          description: 'defines the scale used for calculating and displaying the domain_rank, and url_rank values

            optional field

            you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale

            possible values:

            one_hundred — rank values are displayed on a 0–100 scale

            one_thousand — rank values are displayed on a 0–1000 scale

            default value: one_thousand

            learn more about how this parameter works in this Help Center article'
          nullable: true
        tag:
          type: string
          description: 'user-defined task identifier

            optional field

            the character limit is 255

            you can use this parameter to identify the task and match it with the result

            you will find the specified tag value in the data object of the response'
          nullable: true
      example:
      - keyword_fields:
          snippet: logitech
        keyword: logitech
        page_type:
        - ecommerce
        - news
        - blogs
        - message-boards
        - organization
        search_mode: as_is
        filters:
        - main_domain
        - '='
        - reviewfinder.ca
        order_by:
        - content_info.sentiment_connotations.anger,desc
        limit: 10
    ContentAnalysisIdListTaskInfo:
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseResponseTaskInfo'
      - type: object
        properties:
          result:
            type: array
            items:
              type: object
              oneOf:
              - $ref: '#/components/schemas/ContentAnalysisIdListResultInfo'
              nullable: true
            description: array of results
            nullable: true
    ContentAnalysisCategoryTrendsLiveResultInfo:
      type: object
      properties:
        type:
          type: string
          description: type of element
          nullable: true
        date:
          type: string
          description: date for which the data is provided
          nullable: true
        total_count:
          type: integer
          description: total number of results in our database relevant to your request
          format: int64
          nullable: true
        rank:
          type: integer
          description: 'rank of all URLs citing the keyword

            normalized sum of ranks of all URLs 

# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dataforseo/refs/heads/main/openapi/dataforseo-contentanalysis-api-openapi.yml