mencoro 1.0.0

data/lib/mencoro/api/analytics_api.rb

@@ -0,0 +1,1555 @@
+=begin
+#Mencoro API
+
+#Public API for Mencoro customers. Authenticate with an API key: `Authorization: Bearer mencoro_sk_...`.
+
+The version of the OpenAPI document: 1.0.0
+Contact: support@mencoro.com
+Generated by: https://openapi-generator.tech
+Generator version: 7.24.0
+
+=end
+
+require 'cgi'
+
+module Mencoro
+  class AnalyticsApi
+    attr_accessor :api_client
+
+    def initialize(api_client = ApiClient.default)
+      @api_client = api_client
+    end
+    # Filter values a project is configured for
+    # Minimum role: viewer. Call this first: it is where every other analytics operation sends you for the valid engines, countries and keyword clusters of a project, and the values it returns are the exact strings the engines, countries and queryClusterIds parameters accept — anything else is rejected as a 400. Engines are engine codes, countries are ISO-3166 alpha-2 codes, and clusters are {id, name} objects whose id goes in queryClusterIds. Takes no date window: it describes how the project is configured right now, so a value is listed as soon as a tracked query uses it, even when no response has been captured for it yet. An empty list therefore means nothing is configured for it, not that no data was collected. Competitor ids are not part of this response.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [GetAvailableFilters200Response]
+    def get_available_filters(organization_id, project_id, opts = {})
+      data, _status_code, _headers = get_available_filters_with_http_info(organization_id, project_id, opts)
+      data
+    end
+
+    # Filter values a project is configured for
+    # Minimum role: viewer. Call this first: it is where every other analytics operation sends you for the valid engines, countries and keyword clusters of a project, and the values it returns are the exact strings the engines, countries and queryClusterIds parameters accept — anything else is rejected as a 400. Engines are engine codes, countries are ISO-3166 alpha-2 codes, and clusters are {id, name} objects whose id goes in queryClusterIds. Takes no date window: it describes how the project is configured right now, so a value is listed as soon as a tracked query uses it, even when no response has been captured for it yet. An empty list therefore means nothing is configured for it, not that no data was collected. Competitor ids are not part of this response.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(GetAvailableFilters200Response, Integer, Hash)>] GetAvailableFilters200Response data, response status code and response headers
+    def get_available_filters_with_http_info(organization_id, project_id, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_available_filters ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_available_filters"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.get_available_filters"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/available-filters'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'GetAvailableFilters200Response'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_available_filters",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_available_filters\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Domains and pages the AI answers cited
+    # Minimum role: viewer. The sources the answer engines drew on across a project's AI answers over a date window, ranked by how often they were cited. Per source: citationCount, the total number of citations; distinctResponseCount and distinctQueryCount, how many captured answers and tracked queries it appeared in; avgPosition, its average 1-based rank inside the answers' citation lists, where LOWER is better. A null avgPosition means no citation in the window carried a position, not a rank of zero; a null domain or sampleTitle means the citation never carried one. `total` counts the distinct sources matching the window, before paging. The list is UNFILTERED by ownership: the brand's, competitors' and third-party sources sit in the same ranking. Only the AI answer engines (chatgpt, perplexity, google_ai_overview, google_ai_mode) produce citations, so filtering by google_serp or google_shopping is accepted and returns nothing. Citations still behind an answer engine's redirect (a google.com/goto link, whose URL names the engine rather than the source) are excluded, so a source cited only through such links is absent from this list rather than counted as zero.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated. Only the AI engines carry citations.
+    # @option opts [String] :group_by Grain of the roll-up: \&quot;domain\&quot; by host, \&quot;page\&quot; by exact URL. (default to 'domain')
+    # @option opts [Integer] :limit Page size. A larger value is rejected, never silently reduced. (default to 20)
+    # @option opts [Integer] :offset Number of sources to skip. (default to 0)
+    # @return [nil]
+    def get_cited_sources(organization_id, project_id, date_from, date_to, opts = {})
+      get_cited_sources_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      nil
+    end
+
+    # Domains and pages the AI answers cited
+    # Minimum role: viewer. The sources the answer engines drew on across a project&#39;s AI answers over a date window, ranked by how often they were cited. Per source: citationCount, the total number of citations; distinctResponseCount and distinctQueryCount, how many captured answers and tracked queries it appeared in; avgPosition, its average 1-based rank inside the answers&#39; citation lists, where LOWER is better. A null avgPosition means no citation in the window carried a position, not a rank of zero; a null domain or sampleTitle means the citation never carried one. &#x60;total&#x60; counts the distinct sources matching the window, before paging. The list is UNFILTERED by ownership: the brand&#39;s, competitors&#39; and third-party sources sit in the same ranking. Only the AI answer engines (chatgpt, perplexity, google_ai_overview, google_ai_mode) produce citations, so filtering by google_serp or google_shopping is accepted and returns nothing. Citations still behind an answer engine&#39;s redirect (a google.com/goto link, whose URL names the engine rather than the source) are excluded, so a source cited only through such links is absent from this list rather than counted as zero.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated. Only the AI engines carry citations.
+    # @option opts [String] :group_by Grain of the roll-up: \&quot;domain\&quot; by host, \&quot;page\&quot; by exact URL. (default to 'domain')
+    # @option opts [Integer] :limit Page size. A larger value is rejected, never silently reduced. (default to 20)
+    # @option opts [Integer] :offset Number of sources to skip. (default to 0)
+    # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
+    def get_cited_sources_with_http_info(organization_id, project_id, date_from, date_to, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_cited_sources ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_cited_sources"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.get_cited_sources"
+      end
+      # verify the required parameter 'date_from' is set
+      if @api_client.config.client_side_validation && date_from.nil?
+        fail ArgumentError, "Missing the required parameter 'date_from' when calling AnalyticsApi.get_cited_sources"
+      end
+      # verify the required parameter 'date_to' is set
+      if @api_client.config.client_side_validation && date_to.nil?
+        fail ArgumentError, "Missing the required parameter 'date_to' when calling AnalyticsApi.get_cited_sources"
+      end
+      allowable_values = ["chatgpt", "perplexity", "google_ai_overview", "google_ai_mode", "google_serp", "google_shopping"]
+      if @api_client.config.client_side_validation && opts[:'engines'] && !opts[:'engines'].all? { |item| allowable_values.include?(item) }
+        fail ArgumentError, "invalid value for \"engines\", must include one of #{allowable_values}"
+      end
+      allowable_values = ["domain", "page"]
+      if @api_client.config.client_side_validation && opts[:'group_by'] && !allowable_values.include?(opts[:'group_by'])
+        fail ArgumentError, "invalid value for \"group_by\", must be one of #{allowable_values}"
+      end
+      if @api_client.config.client_side_validation && !opts[:'limit'].nil? && opts[:'limit'] > 100
+        fail ArgumentError, 'invalid value for "opts[:"limit"]" when calling AnalyticsApi.get_cited_sources, must be smaller than or equal to 100.'
+      end
+
+      if @api_client.config.client_side_validation && !opts[:'limit'].nil? && opts[:'limit'] < 1
+        fail ArgumentError, 'invalid value for "opts[:"limit"]" when calling AnalyticsApi.get_cited_sources, must be greater than or equal to 1.'
+      end
+
+      if @api_client.config.client_side_validation && !opts[:'offset'].nil? && opts[:'offset'] < 0
+        fail ArgumentError, 'invalid value for "opts[:"offset"]" when calling AnalyticsApi.get_cited_sources, must be greater than or equal to 0.'
+      end
+
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/cited-sources'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'dateFrom'] = date_from
+      query_params[:'dateTo'] = date_to
+      query_params[:'engines'] = @api_client.build_collection_param(opts[:'engines'], :multi) if !opts[:'engines'].nil?
+      query_params[:'groupBy'] = opts[:'group_by'] if !opts[:'group_by'].nil?
+      query_params[:'limit'] = opts[:'limit'] if !opts[:'limit'].nil?
+      query_params[:'offset'] = opts[:'offset'] if !opts[:'offset'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type]
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_cited_sources",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_cited_sources\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Rank-tracking metrics per keyword cluster
+    # Minimum role: viewer. One row per keyword cluster over a date window, with its tracked query and keyword counts, average positions, rates, share of voice and sentiment split. A row whose clusterId is null is the ungrouped bucket: the tracked queries belonging to no cluster. Position metrics are 1-based and LOWER is better; rates, positivityIndex and shareOfVoice are 0-100 percentages where higher is better. A null metric means nothing was captured for that cluster in the window — it is not a zero, and averaging or charting it as one would misstate the period. dataDirtySince is non-null while a recalculation is pending, meaning the numbers predate the latest configuration change.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [Array<String>] :query_cluster_ids Restrict to these clusters. Each must belong to the project.
+    # @option opts [Boolean] :include_ungrouped_queries Sent alone, returns only the ungrouped bucket rather than adding it to every cluster. (default to false)
+    # @return [nil]
+    def get_cluster_breakdown(organization_id, project_id, date_from, date_to, opts = {})
+      get_cluster_breakdown_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      nil
+    end
+
+    # Rank-tracking metrics per keyword cluster
+    # Minimum role: viewer. One row per keyword cluster over a date window, with its tracked query and keyword counts, average positions, rates, share of voice and sentiment split. A row whose clusterId is null is the ungrouped bucket: the tracked queries belonging to no cluster. Position metrics are 1-based and LOWER is better; rates, positivityIndex and shareOfVoice are 0-100 percentages where higher is better. A null metric means nothing was captured for that cluster in the window — it is not a zero, and averaging or charting it as one would misstate the period. dataDirtySince is non-null while a recalculation is pending, meaning the numbers predate the latest configuration change.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [Array<String>] :query_cluster_ids Restrict to these clusters. Each must belong to the project.
+    # @option opts [Boolean] :include_ungrouped_queries Sent alone, returns only the ungrouped bucket rather than adding it to every cluster. (default to false)
+    # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
+    def get_cluster_breakdown_with_http_info(organization_id, project_id, date_from, date_to, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_cluster_breakdown ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_cluster_breakdown"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.get_cluster_breakdown"
+      end
+      # verify the required parameter 'date_from' is set
+      if @api_client.config.client_side_validation && date_from.nil?
+        fail ArgumentError, "Missing the required parameter 'date_from' when calling AnalyticsApi.get_cluster_breakdown"
+      end
+      # verify the required parameter 'date_to' is set
+      if @api_client.config.client_side_validation && date_to.nil?
+        fail ArgumentError, "Missing the required parameter 'date_to' when calling AnalyticsApi.get_cluster_breakdown"
+      end
+      allowable_values = ["chatgpt", "perplexity", "google_ai_overview", "google_ai_mode", "google_serp", "google_shopping"]
+      if @api_client.config.client_side_validation && opts[:'engines'] && !opts[:'engines'].all? { |item| allowable_values.include?(item) }
+        fail ArgumentError, "invalid value for \"engines\", must include one of #{allowable_values}"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/metrics/clusters'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'dateFrom'] = date_from
+      query_params[:'dateTo'] = date_to
+      query_params[:'engines'] = @api_client.build_collection_param(opts[:'engines'], :multi) if !opts[:'engines'].nil?
+      query_params[:'countries'] = @api_client.build_collection_param(opts[:'countries'], :multi) if !opts[:'countries'].nil?
+      query_params[:'queryClusterIds'] = @api_client.build_collection_param(opts[:'query_cluster_ids'], :multi) if !opts[:'query_cluster_ids'].nil?
+      query_params[:'includeUngroupedQueries'] = opts[:'include_ungrouped_queries'] if !opts[:'include_ungrouped_queries'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type]
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_cluster_breakdown",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_cluster_breakdown\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Head-to-head record of the brand against each tracked competitor
+    # Minimum role: viewer. Restricted to the AI answers where the brand and a competitor are BOTH mentioned, one row per tracked competitor: sharedResponseCount is how many such answers there are, and brandWins / competitorWins / ties split them by who holds the better (lower) best mention position. winRate is the percentage 0-100 of those answers the brand wins; avgOwnPosition and avgCompetitorPosition are the average best mention position each side held, 1-based, so LOWER is better. exampleQueryText and exampleAiResponseId point at one representative shared answer. Every nullable field means \"not known yet\" rather than zero: a null winRate or average position is the absence of a shared answer in the window, not a record of losing. Tracked competitors only.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated. SERP and Shopping carry no AI answer text, so they contribute no co-occurrence.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [String] :competitor_id Restricts the answer to a single tracked competitor. Omit it for every tracked competitor. The available-filters endpoint lists the valid ids.
+    # @return [nil]
+    def get_competitor_co_occurrence(organization_id, project_id, date_from, date_to, opts = {})
+      get_competitor_co_occurrence_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      nil
+    end
+
+    # Head-to-head record of the brand against each tracked competitor
+    # Minimum role: viewer. Restricted to the AI answers where the brand and a competitor are BOTH mentioned, one row per tracked competitor: sharedResponseCount is how many such answers there are, and brandWins / competitorWins / ties split them by who holds the better (lower) best mention position. winRate is the percentage 0-100 of those answers the brand wins; avgOwnPosition and avgCompetitorPosition are the average best mention position each side held, 1-based, so LOWER is better. exampleQueryText and exampleAiResponseId point at one representative shared answer. Every nullable field means \&quot;not known yet\&quot; rather than zero: a null winRate or average position is the absence of a shared answer in the window, not a record of losing. Tracked competitors only.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated. SERP and Shopping carry no AI answer text, so they contribute no co-occurrence.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [String] :competitor_id Restricts the answer to a single tracked competitor. Omit it for every tracked competitor. The available-filters endpoint lists the valid ids.
+    # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
+    def get_competitor_co_occurrence_with_http_info(organization_id, project_id, date_from, date_to, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_competitor_co_occurrence ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_competitor_co_occurrence"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.get_competitor_co_occurrence"
+      end
+      # verify the required parameter 'date_from' is set
+      if @api_client.config.client_side_validation && date_from.nil?
+        fail ArgumentError, "Missing the required parameter 'date_from' when calling AnalyticsApi.get_competitor_co_occurrence"
+      end
+      # verify the required parameter 'date_to' is set
+      if @api_client.config.client_side_validation && date_to.nil?
+        fail ArgumentError, "Missing the required parameter 'date_to' when calling AnalyticsApi.get_competitor_co_occurrence"
+      end
+      allowable_values = ["chatgpt", "perplexity", "google_ai_overview", "google_ai_mode", "google_serp", "google_shopping"]
+      if @api_client.config.client_side_validation && opts[:'engines'] && !opts[:'engines'].all? { |item| allowable_values.include?(item) }
+        fail ArgumentError, "invalid value for \"engines\", must include one of #{allowable_values}"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/competitors/co-occurrence'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'dateFrom'] = date_from
+      query_params[:'dateTo'] = date_to
+      query_params[:'engines'] = @api_client.build_collection_param(opts[:'engines'], :multi) if !opts[:'engines'].nil?
+      query_params[:'countries'] = @api_client.build_collection_param(opts[:'countries'], :multi) if !opts[:'countries'].nil?
+      query_params[:'competitorId'] = opts[:'competitor_id'] if !opts[:'competitor_id'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type]
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_competitor_co_occurrence",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_competitor_co_occurrence\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Composition of a project brand mentions in AI answers
+    # Minimum role: viewer. Counts of the project brand's own text mentions in AI answers over a date window, grouped three ways: byType (recommendation, comparison, listing, example, reference), byTone (positive, neutral, negative) and byQualifier (direct, conditional — a conditional mention is one the answer hedged with a condition). These are the inputs behind the Share of Voice weighted score. Every bucket is always present and is a plain count, never null: a zero means no mention of that kind was found in the window. The three groupings count the same mentions, so each one sums to the same total. Only the project brand is counted, never a competitor, and only mentions inside the answer text — a citation of the brand's URL is not a mention here. Only AI answer engines produce mentions, so restricting engines to google_serp or google_shopping alone returns all zeros. For the positive/neutral/negative split per engine and per competitor use the sentiment endpoint.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated. Non-AI engines contribute no mentions.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @return [nil]
+    def get_mention_mix(organization_id, project_id, date_from, date_to, opts = {})
+      get_mention_mix_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      nil
+    end
+
+    # Composition of a project brand mentions in AI answers
+    # Minimum role: viewer. Counts of the project brand&#39;s own text mentions in AI answers over a date window, grouped three ways: byType (recommendation, comparison, listing, example, reference), byTone (positive, neutral, negative) and byQualifier (direct, conditional — a conditional mention is one the answer hedged with a condition). These are the inputs behind the Share of Voice weighted score. Every bucket is always present and is a plain count, never null: a zero means no mention of that kind was found in the window. The three groupings count the same mentions, so each one sums to the same total. Only the project brand is counted, never a competitor, and only mentions inside the answer text — a citation of the brand&#39;s URL is not a mention here. Only AI answer engines produce mentions, so restricting engines to google_serp or google_shopping alone returns all zeros. For the positive/neutral/negative split per engine and per competitor use the sentiment endpoint.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated. Non-AI engines contribute no mentions.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
+    def get_mention_mix_with_http_info(organization_id, project_id, date_from, date_to, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_mention_mix ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_mention_mix"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.get_mention_mix"
+      end
+      # verify the required parameter 'date_from' is set
+      if @api_client.config.client_side_validation && date_from.nil?
+        fail ArgumentError, "Missing the required parameter 'date_from' when calling AnalyticsApi.get_mention_mix"
+      end
+      # verify the required parameter 'date_to' is set
+      if @api_client.config.client_side_validation && date_to.nil?
+        fail ArgumentError, "Missing the required parameter 'date_to' when calling AnalyticsApi.get_mention_mix"
+      end
+      allowable_values = ["chatgpt", "perplexity", "google_ai_overview", "google_ai_mode", "google_serp", "google_shopping"]
+      if @api_client.config.client_side_validation && opts[:'engines'] && !opts[:'engines'].all? { |item| allowable_values.include?(item) }
+        fail ArgumentError, "invalid value for \"engines\", must include one of #{allowable_values}"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/mentions/mix'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'dateFrom'] = date_from
+      query_params[:'dateTo'] = date_to
+      query_params[:'engines'] = @api_client.build_collection_param(opts[:'engines'], :multi) if !opts[:'engines'].nil?
+      query_params[:'countries'] = @api_client.build_collection_param(opts[:'countries'], :multi) if !opts[:'countries'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type]
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_mention_mix",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_mention_mix\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Sample of the raw AI mention texts of a project
+    # Minimum role: viewer. A paginated page of the individual mention texts behind the aggregate numbers, for qualitative review and for checking sentiment labels by eye. Each sample carries the mention text, the engine and country it was seen in, the tracked query that produced it, its sentiment and mention type, and mentionPosition — a 1-based rank inside the answer where LOWER is better, always present. `total` counts every mention matching the filters, not the size of the page returned. Only mentions inside the answer text are returned: a citation of the brand URL is not a mention here, and only AI answer engines produce mentions, so restricting engines to google_serp or google_shopping alone returns an empty page rather than an error. Two fields carry a \"not known\" rather than a zero: country is null and queryText is empty when the tracked query behind the mention has since been deleted, and competitorId is null when the mention row stores no competitor id — which is NOT an assertion that the mention is about your own brand, since an untracked competitor also stores none. Read mentionRelation instead: `own` and `tracked-competitor` are what the scraper resolved to a configured entity, `untracked-competitor` is a rival the project does not track, and null means the row predates the field. brandName carries the mentioned brand, and is the only way to name an untracked competitor, which has no competitor id to resolve one from. Omitting the competitorId filter returns exactly the rows with no competitor id stored — that is, own-brand AND untracked-competitor mentions together, not every competitor; pass a competitor UUID to restrict the page to that competitor, and use mentionRelation to separate the rest. For the aggregate positive/neutral/negative split use the sentiment endpoint, and for weighted mention-type counts the mention mix endpoint.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated. Non-AI engines contribute no mentions.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [String] :sentiment Restrict to one sentiment label. Omit for every sentiment.
+    # @option opts [String] :mention_type Restrict to one mention type. Omit for every type.
+    # @option opts [String] :competitor_id UUID of a single competitor, as listed by the available-filters endpoint (competitors[].id). Omitted, the page is restricted to mentions storing no competitor id, which is own-brand and untracked-competitor mentions together — see the operation description and read mentionRelation to tell them apart.
+    # @option opts [String] :sort_by recent: newest first. negative: negative sentiment first, then neutral, then positive, newest first inside each. engine and country: grouped alphabetically, newest first inside each group. An unknown value is rejected, not replaced by the default. (default to 'recent')
+    # @option opts [Integer] :limit Page size. A larger value is rejected, never silently reduced. (default to 20)
+    # @option opts [Integer] :offset Number of matching mentions to skip before the page starts. (default to 0)
+    # @return [nil]
+    def get_mention_samples(organization_id, project_id, date_from, date_to, opts = {})
+      get_mention_samples_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      nil
+    end
+
+    # Sample of the raw AI mention texts of a project
+    # Minimum role: viewer. A paginated page of the individual mention texts behind the aggregate numbers, for qualitative review and for checking sentiment labels by eye. Each sample carries the mention text, the engine and country it was seen in, the tracked query that produced it, its sentiment and mention type, and mentionPosition — a 1-based rank inside the answer where LOWER is better, always present. &#x60;total&#x60; counts every mention matching the filters, not the size of the page returned. Only mentions inside the answer text are returned: a citation of the brand URL is not a mention here, and only AI answer engines produce mentions, so restricting engines to google_serp or google_shopping alone returns an empty page rather than an error. Two fields carry a \&quot;not known\&quot; rather than a zero: country is null and queryText is empty when the tracked query behind the mention has since been deleted, and competitorId is null when the mention row stores no competitor id — which is NOT an assertion that the mention is about your own brand, since an untracked competitor also stores none. Read mentionRelation instead: &#x60;own&#x60; and &#x60;tracked-competitor&#x60; are what the scraper resolved to a configured entity, &#x60;untracked-competitor&#x60; is a rival the project does not track, and null means the row predates the field. brandName carries the mentioned brand, and is the only way to name an untracked competitor, which has no competitor id to resolve one from. Omitting the competitorId filter returns exactly the rows with no competitor id stored — that is, own-brand AND untracked-competitor mentions together, not every competitor; pass a competitor UUID to restrict the page to that competitor, and use mentionRelation to separate the rest. For the aggregate positive/neutral/negative split use the sentiment endpoint, and for weighted mention-type counts the mention mix endpoint.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated. Non-AI engines contribute no mentions.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [String] :sentiment Restrict to one sentiment label. Omit for every sentiment.
+    # @option opts [String] :mention_type Restrict to one mention type. Omit for every type.
+    # @option opts [String] :competitor_id UUID of a single competitor, as listed by the available-filters endpoint (competitors[].id). Omitted, the page is restricted to mentions storing no competitor id, which is own-brand and untracked-competitor mentions together — see the operation description and read mentionRelation to tell them apart.
+    # @option opts [String] :sort_by recent: newest first. negative: negative sentiment first, then neutral, then positive, newest first inside each. engine and country: grouped alphabetically, newest first inside each group. An unknown value is rejected, not replaced by the default. (default to 'recent')
+    # @option opts [Integer] :limit Page size. A larger value is rejected, never silently reduced. (default to 20)
+    # @option opts [Integer] :offset Number of matching mentions to skip before the page starts. (default to 0)
+    # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
+    def get_mention_samples_with_http_info(organization_id, project_id, date_from, date_to, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_mention_samples ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_mention_samples"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.get_mention_samples"
+      end
+      # verify the required parameter 'date_from' is set
+      if @api_client.config.client_side_validation && date_from.nil?
+        fail ArgumentError, "Missing the required parameter 'date_from' when calling AnalyticsApi.get_mention_samples"
+      end
+      # verify the required parameter 'date_to' is set
+      if @api_client.config.client_side_validation && date_to.nil?
+        fail ArgumentError, "Missing the required parameter 'date_to' when calling AnalyticsApi.get_mention_samples"
+      end
+      allowable_values = ["chatgpt", "perplexity", "google_ai_overview", "google_ai_mode", "google_serp", "google_shopping"]
+      if @api_client.config.client_side_validation && opts[:'engines'] && !opts[:'engines'].all? { |item| allowable_values.include?(item) }
+        fail ArgumentError, "invalid value for \"engines\", must include one of #{allowable_values}"
+      end
+      allowable_values = ["positive", "neutral", "negative"]
+      if @api_client.config.client_side_validation && opts[:'sentiment'] && !allowable_values.include?(opts[:'sentiment'])
+        fail ArgumentError, "invalid value for \"sentiment\", must be one of #{allowable_values}"
+      end
+      allowable_values = ["recommendation", "comparison", "listing", "example", "reference"]
+      if @api_client.config.client_side_validation && opts[:'mention_type'] && !allowable_values.include?(opts[:'mention_type'])
+        fail ArgumentError, "invalid value for \"mention_type\", must be one of #{allowable_values}"
+      end
+      allowable_values = ["recent", "negative", "engine", "country"]
+      if @api_client.config.client_side_validation && opts[:'sort_by'] && !allowable_values.include?(opts[:'sort_by'])
+        fail ArgumentError, "invalid value for \"sort_by\", must be one of #{allowable_values}"
+      end
+      if @api_client.config.client_side_validation && !opts[:'limit'].nil? && opts[:'limit'] > 100
+        fail ArgumentError, 'invalid value for "opts[:"limit"]" when calling AnalyticsApi.get_mention_samples, must be smaller than or equal to 100.'
+      end
+
+      if @api_client.config.client_side_validation && !opts[:'limit'].nil? && opts[:'limit'] < 1
+        fail ArgumentError, 'invalid value for "opts[:"limit"]" when calling AnalyticsApi.get_mention_samples, must be greater than or equal to 1.'
+      end
+
+      if @api_client.config.client_side_validation && !opts[:'offset'].nil? && opts[:'offset'] < 0
+        fail ArgumentError, 'invalid value for "opts[:"offset"]" when calling AnalyticsApi.get_mention_samples, must be greater than or equal to 0.'
+      end
+
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/mentions'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'dateFrom'] = date_from
+      query_params[:'dateTo'] = date_to
+      query_params[:'engines'] = @api_client.build_collection_param(opts[:'engines'], :multi) if !opts[:'engines'].nil?
+      query_params[:'countries'] = @api_client.build_collection_param(opts[:'countries'], :multi) if !opts[:'countries'].nil?
+      query_params[:'sentiment'] = opts[:'sentiment'] if !opts[:'sentiment'].nil?
+      query_params[:'mentionType'] = opts[:'mention_type'] if !opts[:'mention_type'].nil?
+      query_params[:'competitorId'] = opts[:'competitor_id'] if !opts[:'competitor_id'].nil?
+      query_params[:'sortBy'] = opts[:'sort_by'] if !opts[:'sort_by'].nil?
+      query_params[:'limit'] = opts[:'limit'] if !opts[:'limit'].nil?
+      query_params[:'offset'] = opts[:'offset'] if !opts[:'offset'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type]
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_mention_samples",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_mention_samples\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Map everyday wording to a metric and the operation that serves it
+    # Static reference, no project data. Each entry gives a metric, the everyday words people use for it, its unit and range, whether higher or lower is better, the operation that returns it, and example questions. Useful when turning a vague or non-technical request into the right call.
+    # @param [Hash] opts the optional parameters
+    # @return [GetMetricGlossary200Response]
+    def get_metric_glossary(opts = {})
+      data, _status_code, _headers = get_metric_glossary_with_http_info(opts)
+      data
+    end
+
+    # Map everyday wording to a metric and the operation that serves it
+    # Static reference, no project data. Each entry gives a metric, the everyday words people use for it, its unit and range, whether higher or lower is better, the operation that returns it, and example questions. Useful when turning a vague or non-technical request into the right call.
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(GetMetricGlossary200Response, Integer, Hash)>] GetMetricGlossary200Response data, response status code and response headers
+    def get_metric_glossary_with_http_info(opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_metric_glossary ...'
+      end
+      # resource path
+      local_var_path = '/api/v1/metric-glossary'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'GetMetricGlossary200Response'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_metric_glossary",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_metric_glossary\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Snapshot rank-health board across an organization active projects
+    # Minimum role: viewer. One row per active project — share of voice, mention rate, average mention position, positivity index and tracked-query count — ordered by share of voice, plus an organization-level aggregate of the same metrics. Archived projects are excluded. This is a current-state snapshot and takes no date window; for a date-ranged comparison call the per-project operations (getProjectMetrics, getProjectTimeSeries) for each projectId returned here. Every metric is nullable, and a null means the project has no rank data yet — not a score of zero. Higher is better for shareOfVoice, mentionRate and positivityIndex; avgMentionPosition is a 1-based rank, so LOWER is better.
+    # @param organization_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [GetOrganizationOverview200Response]
+    def get_organization_overview(organization_id, opts = {})
+      data, _status_code, _headers = get_organization_overview_with_http_info(organization_id, opts)
+      data
+    end
+
+    # Snapshot rank-health board across an organization active projects
+    # Minimum role: viewer. One row per active project — share of voice, mention rate, average mention position, positivity index and tracked-query count — ordered by share of voice, plus an organization-level aggregate of the same metrics. Archived projects are excluded. This is a current-state snapshot and takes no date window; for a date-ranged comparison call the per-project operations (getProjectMetrics, getProjectTimeSeries) for each projectId returned here. Every metric is nullable, and a null means the project has no rank data yet — not a score of zero. Higher is better for shareOfVoice, mentionRate and positivityIndex; avgMentionPosition is a 1-based rank, so LOWER is better.
+    # @param organization_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(GetOrganizationOverview200Response, Integer, Hash)>] GetOrganizationOverview200Response data, response status code and response headers
+    def get_organization_overview_with_http_info(organization_id, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_organization_overview ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_organization_overview"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/overview'.sub('{organizationId}', CGI.escape(organization_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'GetOrganizationOverview200Response'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_organization_overview",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_organization_overview\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Headline visibility metrics of a project
+    # Minimum role: viewer. The project overview over a date window: share of voice (own and per competitor), mention / SERP / shopping rates, average and best positions, position stability, the sentiment split and the position-distribution buckets. Positions are 1-based, so a LOWER number is better; rates, the positivity index and share of voice are percentages from 0 to 100, where HIGHER is better. Every `trend*` field is the signed change against the immediately preceding window of the same length: negative means an improved position, positive means an improved rate or score. A null metric means \"not known yet\", never zero: a scalar is null when the window holds no checks at all, and a `trend*` field is null when there is no earlier window to compare against. The counters (`mentionCount`, `*TrackedQueryCount`, `*QueriesWithResult`, `sentiment*` and `mentionTypeCounts`) are genuine zeros instead, so an empty window reads as zero counts with null rates. `dataDirtySince` is non-null while a recalculation is pending, meaning the figures may still move for dates from then on.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [Array<String>] :query_cluster_ids Restrict to these keyword clusters. Each must belong to this project.
+    # @option opts [Boolean] :include_ungrouped_queries Only meaningful together with queryClusterIds: also counts the tracked queries that belong to no cluster. (default to false)
+    # @return [nil]
+    def get_project_metrics(organization_id, project_id, date_from, date_to, opts = {})
+      get_project_metrics_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      nil
+    end
+
+    # Headline visibility metrics of a project
+    # Minimum role: viewer. The project overview over a date window: share of voice (own and per competitor), mention / SERP / shopping rates, average and best positions, position stability, the sentiment split and the position-distribution buckets. Positions are 1-based, so a LOWER number is better; rates, the positivity index and share of voice are percentages from 0 to 100, where HIGHER is better. Every &#x60;trend*&#x60; field is the signed change against the immediately preceding window of the same length: negative means an improved position, positive means an improved rate or score. A null metric means \&quot;not known yet\&quot;, never zero: a scalar is null when the window holds no checks at all, and a &#x60;trend*&#x60; field is null when there is no earlier window to compare against. The counters (&#x60;mentionCount&#x60;, &#x60;*TrackedQueryCount&#x60;, &#x60;*QueriesWithResult&#x60;, &#x60;sentiment*&#x60; and &#x60;mentionTypeCounts&#x60;) are genuine zeros instead, so an empty window reads as zero counts with null rates. &#x60;dataDirtySince&#x60; is non-null while a recalculation is pending, meaning the figures may still move for dates from then on.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [Array<String>] :query_cluster_ids Restrict to these keyword clusters. Each must belong to this project.
+    # @option opts [Boolean] :include_ungrouped_queries Only meaningful together with queryClusterIds: also counts the tracked queries that belong to no cluster. (default to false)
+    # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
+    def get_project_metrics_with_http_info(organization_id, project_id, date_from, date_to, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_project_metrics ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_project_metrics"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.get_project_metrics"
+      end
+      # verify the required parameter 'date_from' is set
+      if @api_client.config.client_side_validation && date_from.nil?
+        fail ArgumentError, "Missing the required parameter 'date_from' when calling AnalyticsApi.get_project_metrics"
+      end
+      # verify the required parameter 'date_to' is set
+      if @api_client.config.client_side_validation && date_to.nil?
+        fail ArgumentError, "Missing the required parameter 'date_to' when calling AnalyticsApi.get_project_metrics"
+      end
+      allowable_values = ["chatgpt", "perplexity", "google_ai_overview", "google_ai_mode", "google_serp", "google_shopping"]
+      if @api_client.config.client_side_validation && opts[:'engines'] && !opts[:'engines'].all? { |item| allowable_values.include?(item) }
+        fail ArgumentError, "invalid value for \"engines\", must include one of #{allowable_values}"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/metrics'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'dateFrom'] = date_from
+      query_params[:'dateTo'] = date_to
+      query_params[:'engines'] = @api_client.build_collection_param(opts[:'engines'], :multi) if !opts[:'engines'].nil?
+      query_params[:'countries'] = @api_client.build_collection_param(opts[:'countries'], :multi) if !opts[:'countries'].nil?
+      query_params[:'queryClusterIds'] = @api_client.build_collection_param(opts[:'query_cluster_ids'], :multi) if !opts[:'query_cluster_ids'].nil?
+      query_params[:'includeUngroupedQueries'] = opts[:'include_ungrouped_queries'] if !opts[:'include_ungrouped_queries'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type]
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_project_metrics",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_project_metrics\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Sentiment breakdown of a project brand mentions
+    # Minimum role: viewer. Positive, neutral and negative split of the brand mentions in AI answers over a date window, per engine and per competitor. A null positivityIndex means no mentions were found in the window, which is not the same as a score of zero.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [Array<String>] :query_cluster_ids 
+    # @option opts [Boolean] :include_ungrouped_queries  (default to false)
+    # @return [nil]
+    def get_project_sentiment(organization_id, project_id, date_from, date_to, opts = {})
+      get_project_sentiment_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      nil
+    end
+
+    # Sentiment breakdown of a project brand mentions
+    # Minimum role: viewer. Positive, neutral and negative split of the brand mentions in AI answers over a date window, per engine and per competitor. A null positivityIndex means no mentions were found in the window, which is not the same as a score of zero.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [Array<String>] :query_cluster_ids 
+    # @option opts [Boolean] :include_ungrouped_queries  (default to false)
+    # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
+    def get_project_sentiment_with_http_info(organization_id, project_id, date_from, date_to, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_project_sentiment ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_project_sentiment"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.get_project_sentiment"
+      end
+      # verify the required parameter 'date_from' is set
+      if @api_client.config.client_side_validation && date_from.nil?
+        fail ArgumentError, "Missing the required parameter 'date_from' when calling AnalyticsApi.get_project_sentiment"
+      end
+      # verify the required parameter 'date_to' is set
+      if @api_client.config.client_side_validation && date_to.nil?
+        fail ArgumentError, "Missing the required parameter 'date_to' when calling AnalyticsApi.get_project_sentiment"
+      end
+      allowable_values = ["chatgpt", "perplexity", "google_ai_overview", "google_ai_mode", "google_serp", "google_shopping"]
+      if @api_client.config.client_side_validation && opts[:'engines'] && !opts[:'engines'].all? { |item| allowable_values.include?(item) }
+        fail ArgumentError, "invalid value for \"engines\", must include one of #{allowable_values}"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/sentiment'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'dateFrom'] = date_from
+      query_params[:'dateTo'] = date_to
+      query_params[:'engines'] = @api_client.build_collection_param(opts[:'engines'], :multi) if !opts[:'engines'].nil?
+      query_params[:'countries'] = @api_client.build_collection_param(opts[:'countries'], :multi) if !opts[:'countries'].nil?
+      query_params[:'queryClusterIds'] = @api_client.build_collection_param(opts[:'query_cluster_ids'], :multi) if !opts[:'query_cluster_ids'].nil?
+      query_params[:'includeUngroupedQueries'] = opts[:'include_ungrouped_queries'] if !opts[:'include_ungrouped_queries'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type]
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_project_sentiment",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_project_sentiment\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Rank-tracking metrics of a project over time
+    # Minimum role: viewer. One point per bucket over the date window, each carrying the brand metrics and one same-shaped entry per requested competitor. Rank metrics (serp, shopping, mention, link) are 1-based averages where LOWER is better; positivity (0-100), shareOfVoice (0-100), mentionRate (0-100) and serpRate (0-100) are scores where higher is better. Every metric is nullable, and a null means no data was collected for that bucket, which is not the same as a value of zero. A project with no tracked queries returns an empty points list. Prefer weekly or monthly granularity over a long window to keep the response compact.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [String] :granularity Bucket size of each point. (default to 'daily')
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [Array<String>] :query_cluster_ids 
+    # @option opts [Boolean] :include_ungrouped_queries On its own this NARROWS the series to tracked queries that belong to no cluster; combined with queryClusterIds it widens those clusters to also cover them. (default to false)
+    # @option opts [Array<String>] :competitor_ids Repeatable, or comma-separated. Each id adds one series under the competitors map of every point.
+    # @return [nil]
+    def get_project_time_series(organization_id, project_id, date_from, date_to, opts = {})
+      get_project_time_series_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      nil
+    end
+
+    # Rank-tracking metrics of a project over time
+    # Minimum role: viewer. One point per bucket over the date window, each carrying the brand metrics and one same-shaped entry per requested competitor. Rank metrics (serp, shopping, mention, link) are 1-based averages where LOWER is better; positivity (0-100), shareOfVoice (0-100), mentionRate (0-100) and serpRate (0-100) are scores where higher is better. Every metric is nullable, and a null means no data was collected for that bucket, which is not the same as a value of zero. A project with no tracked queries returns an empty points list. Prefer weekly or monthly granularity over a long window to keep the response compact.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [String] :granularity Bucket size of each point. (default to 'daily')
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [Array<String>] :query_cluster_ids 
+    # @option opts [Boolean] :include_ungrouped_queries On its own this NARROWS the series to tracked queries that belong to no cluster; combined with queryClusterIds it widens those clusters to also cover them. (default to false)
+    # @option opts [Array<String>] :competitor_ids Repeatable, or comma-separated. Each id adds one series under the competitors map of every point.
+    # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
+    def get_project_time_series_with_http_info(organization_id, project_id, date_from, date_to, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_project_time_series ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_project_time_series"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.get_project_time_series"
+      end
+      # verify the required parameter 'date_from' is set
+      if @api_client.config.client_side_validation && date_from.nil?
+        fail ArgumentError, "Missing the required parameter 'date_from' when calling AnalyticsApi.get_project_time_series"
+      end
+      # verify the required parameter 'date_to' is set
+      if @api_client.config.client_side_validation && date_to.nil?
+        fail ArgumentError, "Missing the required parameter 'date_to' when calling AnalyticsApi.get_project_time_series"
+      end
+      allowable_values = ["daily", "weekly", "monthly"]
+      if @api_client.config.client_side_validation && opts[:'granularity'] && !allowable_values.include?(opts[:'granularity'])
+        fail ArgumentError, "invalid value for \"granularity\", must be one of #{allowable_values}"
+      end
+      allowable_values = ["chatgpt", "perplexity", "google_ai_overview", "google_ai_mode", "google_serp", "google_shopping"]
+      if @api_client.config.client_side_validation && opts[:'engines'] && !opts[:'engines'].all? { |item| allowable_values.include?(item) }
+        fail ArgumentError, "invalid value for \"engines\", must include one of #{allowable_values}"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/timeseries'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'dateFrom'] = date_from
+      query_params[:'dateTo'] = date_to
+      query_params[:'granularity'] = opts[:'granularity'] if !opts[:'granularity'].nil?
+      query_params[:'engines'] = @api_client.build_collection_param(opts[:'engines'], :multi) if !opts[:'engines'].nil?
+      query_params[:'countries'] = @api_client.build_collection_param(opts[:'countries'], :multi) if !opts[:'countries'].nil?
+      query_params[:'queryClusterIds'] = @api_client.build_collection_param(opts[:'query_cluster_ids'], :multi) if !opts[:'query_cluster_ids'].nil?
+      query_params[:'includeUngroupedQueries'] = opts[:'include_ungrouped_queries'] if !opts[:'include_ungrouped_queries'].nil?
+      query_params[:'competitorIds'] = @api_client.build_collection_param(opts[:'competitor_ids'], :multi) if !opts[:'competitor_ids'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type]
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_project_time_series",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_project_time_series\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Tracked queries ranked by how much a metric moved
+    # Minimum role: viewer. One row per tracked query — a single engine plus country — carrying its current metric envelope and the signed change against the immediately preceding window of equal length: a 7-day window is compared with the 7 days before it. Every trend delta is signed so that POSITIVE means improved, including the position trends, where the underlying avgSerpPosition / avgShoppingPosition / avgMentionPosition / avgLinkPosition are 1-based ranks and therefore LOWER is better. shareOfVoice and positivityIndex are percentages from 0 to 100, where HIGHER is better. Sorting applies to the trend keys only: sortOrder=desc gives the top gainers, asc the top losers. Every nullable field means \"not known yet\" rather than zero — a null position or shareOfVoice is a query with no data in the window, and a null positivityIndex or trend is a period with no mentions to score, neither of which is a record of losing ground. total counts the tracked queries the filters match, not the rows on this page. dataDirtySince is a date from which the rank data is being recomputed, or null when nothing is pending; while it is non-null the deltas may still move.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window. The comparison window is the equally long stretch immediately before it.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [String] :sort_by Which trend delta ranks the rows. Positions improve as they fall, so a positive delta is always an improvement whichever key you pick. An unknown value is rejected, not replaced by the default. (default to 'trend_share_of_voice')
+    # @option opts [String] :sort_order desc for the top gainers, asc for the top losers. (default to 'desc')
+    # @option opts [Integer] :limit Page size. A value above the maximum is rejected, never clamped. (default to 20)
+    # @option opts [Integer] :offset  (default to 0)
+    # @return [nil]
+    def get_query_movers(organization_id, project_id, date_from, date_to, opts = {})
+      get_query_movers_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      nil
+    end
+
+    # Tracked queries ranked by how much a metric moved
+    # Minimum role: viewer. One row per tracked query — a single engine plus country — carrying its current metric envelope and the signed change against the immediately preceding window of equal length: a 7-day window is compared with the 7 days before it. Every trend delta is signed so that POSITIVE means improved, including the position trends, where the underlying avgSerpPosition / avgShoppingPosition / avgMentionPosition / avgLinkPosition are 1-based ranks and therefore LOWER is better. shareOfVoice and positivityIndex are percentages from 0 to 100, where HIGHER is better. Sorting applies to the trend keys only: sortOrder&#x3D;desc gives the top gainers, asc the top losers. Every nullable field means \&quot;not known yet\&quot; rather than zero — a null position or shareOfVoice is a query with no data in the window, and a null positivityIndex or trend is a period with no mentions to score, neither of which is a record of losing ground. total counts the tracked queries the filters match, not the rows on this page. dataDirtySince is a date from which the rank data is being recomputed, or null when nothing is pending; while it is non-null the deltas may still move.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window. The comparison window is the equally long stretch immediately before it.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [String] :sort_by Which trend delta ranks the rows. Positions improve as they fall, so a positive delta is always an improvement whichever key you pick. An unknown value is rejected, not replaced by the default. (default to 'trend_share_of_voice')
+    # @option opts [String] :sort_order desc for the top gainers, asc for the top losers. (default to 'desc')
+    # @option opts [Integer] :limit Page size. A value above the maximum is rejected, never clamped. (default to 20)
+    # @option opts [Integer] :offset  (default to 0)
+    # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
+    def get_query_movers_with_http_info(organization_id, project_id, date_from, date_to, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_query_movers ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_query_movers"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.get_query_movers"
+      end
+      # verify the required parameter 'date_from' is set
+      if @api_client.config.client_side_validation && date_from.nil?
+        fail ArgumentError, "Missing the required parameter 'date_from' when calling AnalyticsApi.get_query_movers"
+      end
+      # verify the required parameter 'date_to' is set
+      if @api_client.config.client_side_validation && date_to.nil?
+        fail ArgumentError, "Missing the required parameter 'date_to' when calling AnalyticsApi.get_query_movers"
+      end
+      allowable_values = ["chatgpt", "perplexity", "google_ai_overview", "google_ai_mode", "google_serp", "google_shopping"]
+      if @api_client.config.client_side_validation && opts[:'engines'] && !opts[:'engines'].all? { |item| allowable_values.include?(item) }
+        fail ArgumentError, "invalid value for \"engines\", must include one of #{allowable_values}"
+      end
+      allowable_values = ["trend_serp", "trend_shopping", "trend_mention", "trend_link", "trend_share_of_voice"]
+      if @api_client.config.client_side_validation && opts[:'sort_by'] && !allowable_values.include?(opts[:'sort_by'])
+        fail ArgumentError, "invalid value for \"sort_by\", must be one of #{allowable_values}"
+      end
+      allowable_values = ["asc", "desc"]
+      if @api_client.config.client_side_validation && opts[:'sort_order'] && !allowable_values.include?(opts[:'sort_order'])
+        fail ArgumentError, "invalid value for \"sort_order\", must be one of #{allowable_values}"
+      end
+      if @api_client.config.client_side_validation && !opts[:'limit'].nil? && opts[:'limit'] > 100
+        fail ArgumentError, 'invalid value for "opts[:"limit"]" when calling AnalyticsApi.get_query_movers, must be smaller than or equal to 100.'
+      end
+
+      if @api_client.config.client_side_validation && !opts[:'limit'].nil? && opts[:'limit'] < 1
+        fail ArgumentError, 'invalid value for "opts[:"limit"]" when calling AnalyticsApi.get_query_movers, must be greater than or equal to 1.'
+      end
+
+      if @api_client.config.client_side_validation && !opts[:'offset'].nil? && opts[:'offset'] < 0
+        fail ArgumentError, 'invalid value for "opts[:"offset"]" when calling AnalyticsApi.get_query_movers, must be greater than or equal to 0.'
+      end
+
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/metrics/movers'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'dateFrom'] = date_from
+      query_params[:'dateTo'] = date_to
+      query_params[:'engines'] = @api_client.build_collection_param(opts[:'engines'], :multi) if !opts[:'engines'].nil?
+      query_params[:'countries'] = @api_client.build_collection_param(opts[:'countries'], :multi) if !opts[:'countries'].nil?
+      query_params[:'sortBy'] = opts[:'sort_by'] if !opts[:'sort_by'].nil?
+      query_params[:'sortOrder'] = opts[:'sort_order'] if !opts[:'sort_order'].nil?
+      query_params[:'limit'] = opts[:'limit'] if !opts[:'limit'].nil?
+      query_params[:'offset'] = opts[:'offset'] if !opts[:'offset'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type]
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_query_movers",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_query_movers\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # The constants behind the Share of Voice score
+    # Minimum role: viewer. Static reference data, the same for every project: the weights and multipliers that turn individual brand mentions into a Share of Voice score. Each mention is worth `mentionTypeWeights[type] * sentimentMultipliers[tone] * (conditional ? conditionalMultiplier : directMultiplier)`, and a competitor's Share of Voice is its share of the summed weights of every brand in the window, as a percentage. mentionTypeWeights is keyed by mention type (recommendation, comparison, listing, example, reference) and sentimentMultipliers by tone (positive, neutral, negative); a negative mention is discounted, not discarded, because it still evidences presence. A conditional mention is one the answer hedged with a condition (\"if you need X\"). Use this to explain a score, not to recompute one: the counts it applies to come from the mention mix endpoint. Every value is always present and is never null.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [GetShareOfVoiceFormula200Response]
+    def get_share_of_voice_formula(organization_id, project_id, opts = {})
+      data, _status_code, _headers = get_share_of_voice_formula_with_http_info(organization_id, project_id, opts)
+      data
+    end
+
+    # The constants behind the Share of Voice score
+    # Minimum role: viewer. Static reference data, the same for every project: the weights and multipliers that turn individual brand mentions into a Share of Voice score. Each mention is worth &#x60;mentionTypeWeights[type] * sentimentMultipliers[tone] * (conditional ? conditionalMultiplier : directMultiplier)&#x60;, and a competitor&#39;s Share of Voice is its share of the summed weights of every brand in the window, as a percentage. mentionTypeWeights is keyed by mention type (recommendation, comparison, listing, example, reference) and sentimentMultipliers by tone (positive, neutral, negative); a negative mention is discounted, not discarded, because it still evidences presence. A conditional mention is one the answer hedged with a condition (\&quot;if you need X\&quot;). Use this to explain a score, not to recompute one: the counts it applies to come from the mention mix endpoint. Every value is always present and is never null.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(GetShareOfVoiceFormula200Response, Integer, Hash)>] GetShareOfVoiceFormula200Response data, response status code and response headers
+    def get_share_of_voice_formula_with_http_info(organization_id, project_id, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_share_of_voice_formula ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_share_of_voice_formula"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.get_share_of_voice_formula"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/metrics/share-of-voice-formula'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'GetShareOfVoiceFormula200Response'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_share_of_voice_formula",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_share_of_voice_formula\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Rank-tracking time series of a single tracked query
+    # Minimum role: viewer. One point per bucket over the date window, each carrying the brand metrics and one same-shaped entry per requested competitor. Positions (serp, shopping, mention, link) are 1-based, so a LOWER number is better; positivity, shareOfVoice, mentionRate and serpRate are percentages from 0 to 100, where higher is better. Every metric is nullable, and a null means nothing was captured for that entity in that bucket — it is not a zero: a null shareOfVoice means no measurement, a shareOfVoice of 0 means measured and never mentioned. The tracked query fixes its own engine and country, so no engine or country filter is accepted. A non-null dataDirtySince is a timestamp warning that tracked queries were deleted from the project and historical buckets may still include their contributions until the nightly refresh rebuilds them.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param tracked_query_id [String] Must belong to the project in the path.
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [String] :granularity Bucket size. Prefer weekly or monthly for long windows. (default to 'daily')
+    # @option opts [Array<String>] :competitor_ids Competitors to add as extra series, repeatable or comma-separated. Valid ids come from the available-filters endpoint.
+    # @return [nil]
+    def get_tracked_query_time_series(organization_id, project_id, tracked_query_id, date_from, date_to, opts = {})
+      get_tracked_query_time_series_with_http_info(organization_id, project_id, tracked_query_id, date_from, date_to, opts)
+      nil
+    end
+
+    # Rank-tracking time series of a single tracked query
+    # Minimum role: viewer. One point per bucket over the date window, each carrying the brand metrics and one same-shaped entry per requested competitor. Positions (serp, shopping, mention, link) are 1-based, so a LOWER number is better; positivity, shareOfVoice, mentionRate and serpRate are percentages from 0 to 100, where higher is better. Every metric is nullable, and a null means nothing was captured for that entity in that bucket — it is not a zero: a null shareOfVoice means no measurement, a shareOfVoice of 0 means measured and never mentioned. The tracked query fixes its own engine and country, so no engine or country filter is accepted. A non-null dataDirtySince is a timestamp warning that tracked queries were deleted from the project and historical buckets may still include their contributions until the nightly refresh rebuilds them.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param tracked_query_id [String] Must belong to the project in the path.
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d.
+    # @param [Hash] opts the optional parameters
+    # @option opts [String] :granularity Bucket size. Prefer weekly or monthly for long windows. (default to 'daily')
+    # @option opts [Array<String>] :competitor_ids Competitors to add as extra series, repeatable or comma-separated. Valid ids come from the available-filters endpoint.
+    # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
+    def get_tracked_query_time_series_with_http_info(organization_id, project_id, tracked_query_id, date_from, date_to, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_tracked_query_time_series ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_tracked_query_time_series"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.get_tracked_query_time_series"
+      end
+      # verify the required parameter 'tracked_query_id' is set
+      if @api_client.config.client_side_validation && tracked_query_id.nil?
+        fail ArgumentError, "Missing the required parameter 'tracked_query_id' when calling AnalyticsApi.get_tracked_query_time_series"
+      end
+      # verify the required parameter 'date_from' is set
+      if @api_client.config.client_side_validation && date_from.nil?
+        fail ArgumentError, "Missing the required parameter 'date_from' when calling AnalyticsApi.get_tracked_query_time_series"
+      end
+      # verify the required parameter 'date_to' is set
+      if @api_client.config.client_side_validation && date_to.nil?
+        fail ArgumentError, "Missing the required parameter 'date_to' when calling AnalyticsApi.get_tracked_query_time_series"
+      end
+      allowable_values = ["daily", "weekly", "monthly"]
+      if @api_client.config.client_side_validation && opts[:'granularity'] && !allowable_values.include?(opts[:'granularity'])
+        fail ArgumentError, "invalid value for \"granularity\", must be one of #{allowable_values}"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/tracked-queries/{trackedQueryId}/timeseries'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s)).sub('{trackedQueryId}', CGI.escape(tracked_query_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'dateFrom'] = date_from
+      query_params[:'dateTo'] = date_to
+      query_params[:'granularity'] = opts[:'granularity'] if !opts[:'granularity'].nil?
+      query_params[:'competitorIds'] = @api_client.build_collection_param(opts[:'competitor_ids'], :multi) if !opts[:'competitor_ids'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type]
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_tracked_query_time_series",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_tracked_query_time_series\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Coverage and staleness of a project tracked queries
+    # Minimum role: viewer. A current-state snapshot answering \"what is stale or not being tracked\": total is every tracked query on the project, active and paused split it by status, neverChecked counts the active queries that have never run, and overdue counts the active queries whose last check is older than their own check-frequency interval (daily, weekly or monthly). neverChecked and overdue are disjoint — a query that has never run is never also counted as overdue — and both ignore paused queries, which are not expected to be checked at all. sample lists up to 20 of the overdue queries, most stale first; it is a sample of overdue only, so it never contains a never-checked query and is empty when overdue is 0. Takes no date window: every count describes the project as it stands right now.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [GetTrackingCoverage200Response]
+    def get_tracking_coverage(organization_id, project_id, opts = {})
+      data, _status_code, _headers = get_tracking_coverage_with_http_info(organization_id, project_id, opts)
+      data
+    end
+
+    # Coverage and staleness of a project tracked queries
+    # Minimum role: viewer. A current-state snapshot answering \&quot;what is stale or not being tracked\&quot;: total is every tracked query on the project, active and paused split it by status, neverChecked counts the active queries that have never run, and overdue counts the active queries whose last check is older than their own check-frequency interval (daily, weekly or monthly). neverChecked and overdue are disjoint — a query that has never run is never also counted as overdue — and both ignore paused queries, which are not expected to be checked at all. sample lists up to 20 of the overdue queries, most stale first; it is a sample of overdue only, so it never contains a never-checked query and is empty when overdue is 0. Takes no date window: every count describes the project as it stands right now.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(GetTrackingCoverage200Response, Integer, Hash)>] GetTrackingCoverage200Response data, response status code and response headers
+    def get_tracking_coverage_with_http_info(organization_id, project_id, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.get_tracking_coverage ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.get_tracking_coverage"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.get_tracking_coverage"
+      end
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/coverage'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'GetTrackingCoverage200Response'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.get_tracking_coverage",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#get_tracking_coverage\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # List a project's keywords with their windowed metrics
+    # Minimum role: viewer. One row per distinct keyword text of the project — every tracked query asking that text, on any engine in any country, collapsed into a single row whose variantIds name the tracked queries behind it. Each row carries the metrics of the requested window and a signed trend against the window of equal length immediately before it, where POSITIVE ALWAYS MEANS BETTER whichever direction the metric itself runs. Positions are 1-based and lower is better; rates, positivityIndex and shareOfVoice are 0-100 and higher is better; mentionPositionStability is a day-to-day spread, so lower is steadier. A null metric means nothing was captured for that keyword in the window — it is not a zero. `total` counts the KEYWORDS matching the filters, not the rows on this page and not tracked queries; `totalVariantCount` counts the tracked queries behind the keywords matching every filter EXCEPT `search` — with a text search applied it still counts the project's variants, so do not size a force-check budget from it on a searched page. NEITHER IS THE PROJECT'S TRACKED-QUERY COUNT: the count operation reads the write model, while this listing reads projections refreshed in the background from it, so the numbers legitimately differ while those projections catch up. A project whose cached tracked-query count has not been refreshed yet answers an empty page with total 0 — the same answer as a project with no tracked queries at all — so treat an unexpected empty page right after creating queries as \"not projected yet\", not as \"no data\". dataDirtySince is non-null while a recalculation is pending, meaning the metrics predate the latest configuration change. Filters narrow which VARIANTS count towards a row, so engines, countries, statuses, checkFrequencies and nPassesValues each report what the filters selected rather than everything the keyword has. A filter or sort key this endpoint cannot honour is rejected by name, never ignored, and a limit above the maximum is rejected rather than quietly reduced. This operation answers JSON only: a keyword row carries a nested mentionTypeCounts object, so it is not part of the CSV family.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d. The trend compares against the equally long window ending the day before dateFrom.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated. Narrows which variants count towards each row.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [Array<String>] :query_cluster_ids Restrict to keywords with a variant in these clusters. Each must belong to the project.
+    # @option opts [Boolean] :include_ungrouped_queries Sent alone, restricts the listing to keywords whose variants belong to no cluster; sent with queryClusterIds, adds them to that selection. (default to false)
+    # @option opts [String] :status Restrict to variants with this status. A keyword whose variants disagree still reports statusSummary \&quot;mixed\&quot;.
+    # @option opts [Array<String>] :check_frequencies Repeatable, or comma-separated.
+    # @option opts [Array<Integer>] :n_passes Repeatable, or comma-separated. Restrict to variants configured with these pass counts.
+    # @option opts [String] :search Case-insensitive substring match on the keyword text.
+    # @option opts [String] :sort_by Named after the field it orders by. Rows with no value for the chosen key sort last in either direction. An unknown key is rejected, not replaced by the default. (default to 'keyword')
+    # @option opts [String] :sort_order  (default to 'asc')
+    # @option opts [Integer] :limit Page size. A larger value is rejected, never silently reduced. (default to 20)
+    # @option opts [Integer] :offset Number of matching keywords to skip before the page starts. (default to 0)
+    # @return [ListKeywordListings200Response]
+    def list_keyword_listings(organization_id, project_id, date_from, date_to, opts = {})
+      data, _status_code, _headers = list_keyword_listings_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      data
+    end
+
+    # List a project&#39;s keywords with their windowed metrics
+    # Minimum role: viewer. One row per distinct keyword text of the project — every tracked query asking that text, on any engine in any country, collapsed into a single row whose variantIds name the tracked queries behind it. Each row carries the metrics of the requested window and a signed trend against the window of equal length immediately before it, where POSITIVE ALWAYS MEANS BETTER whichever direction the metric itself runs. Positions are 1-based and lower is better; rates, positivityIndex and shareOfVoice are 0-100 and higher is better; mentionPositionStability is a day-to-day spread, so lower is steadier. A null metric means nothing was captured for that keyword in the window — it is not a zero. &#x60;total&#x60; counts the KEYWORDS matching the filters, not the rows on this page and not tracked queries; &#x60;totalVariantCount&#x60; counts the tracked queries behind the keywords matching every filter EXCEPT &#x60;search&#x60; — with a text search applied it still counts the project&#39;s variants, so do not size a force-check budget from it on a searched page. NEITHER IS THE PROJECT&#39;S TRACKED-QUERY COUNT: the count operation reads the write model, while this listing reads projections refreshed in the background from it, so the numbers legitimately differ while those projections catch up. A project whose cached tracked-query count has not been refreshed yet answers an empty page with total 0 — the same answer as a project with no tracked queries at all — so treat an unexpected empty page right after creating queries as \&quot;not projected yet\&quot;, not as \&quot;no data\&quot;. dataDirtySince is non-null while a recalculation is pending, meaning the metrics predate the latest configuration change. Filters narrow which VARIANTS count towards a row, so engines, countries, statuses, checkFrequencies and nPassesValues each report what the filters selected rather than everything the keyword has. A filter or sort key this endpoint cannot honour is rejected by name, never ignored, and a limit above the maximum is rejected rather than quietly reduced. This operation answers JSON only: a keyword row carries a nested mentionTypeCounts object, so it is not part of the CSV family.
+    # @param organization_id [String] 
+    # @param project_id [String] 
+    # @param date_from [Date] Inclusive start of the window, Y-m-d. Must fall inside the data retention window.
+    # @param date_to [Date] Inclusive end of the window, Y-m-d. The trend compares against the equally long window ending the day before dateFrom.
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :engines Repeatable, or comma-separated. Narrows which variants count towards each row.
+    # @option opts [Array<String>] :countries ISO-3166 alpha-2 codes or English names. Must be configured on the project.
+    # @option opts [Array<String>] :query_cluster_ids Restrict to keywords with a variant in these clusters. Each must belong to the project.
+    # @option opts [Boolean] :include_ungrouped_queries Sent alone, restricts the listing to keywords whose variants belong to no cluster; sent with queryClusterIds, adds them to that selection. (default to false)
+    # @option opts [String] :status Restrict to variants with this status. A keyword whose variants disagree still reports statusSummary \&quot;mixed\&quot;.
+    # @option opts [Array<String>] :check_frequencies Repeatable, or comma-separated.
+    # @option opts [Array<Integer>] :n_passes Repeatable, or comma-separated. Restrict to variants configured with these pass counts.
+    # @option opts [String] :search Case-insensitive substring match on the keyword text.
+    # @option opts [String] :sort_by Named after the field it orders by. Rows with no value for the chosen key sort last in either direction. An unknown key is rejected, not replaced by the default. (default to 'keyword')
+    # @option opts [String] :sort_order  (default to 'asc')
+    # @option opts [Integer] :limit Page size. A larger value is rejected, never silently reduced. (default to 20)
+    # @option opts [Integer] :offset Number of matching keywords to skip before the page starts. (default to 0)
+    # @return [Array<(ListKeywordListings200Response, Integer, Hash)>] ListKeywordListings200Response data, response status code and response headers
+    def list_keyword_listings_with_http_info(organization_id, project_id, date_from, date_to, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AnalyticsApi.list_keyword_listings ...'
+      end
+      # verify the required parameter 'organization_id' is set
+      if @api_client.config.client_side_validation && organization_id.nil?
+        fail ArgumentError, "Missing the required parameter 'organization_id' when calling AnalyticsApi.list_keyword_listings"
+      end
+      # verify the required parameter 'project_id' is set
+      if @api_client.config.client_side_validation && project_id.nil?
+        fail ArgumentError, "Missing the required parameter 'project_id' when calling AnalyticsApi.list_keyword_listings"
+      end
+      # verify the required parameter 'date_from' is set
+      if @api_client.config.client_side_validation && date_from.nil?
+        fail ArgumentError, "Missing the required parameter 'date_from' when calling AnalyticsApi.list_keyword_listings"
+      end
+      # verify the required parameter 'date_to' is set
+      if @api_client.config.client_side_validation && date_to.nil?
+        fail ArgumentError, "Missing the required parameter 'date_to' when calling AnalyticsApi.list_keyword_listings"
+      end
+      allowable_values = ["chatgpt", "perplexity", "google_ai_overview", "google_ai_mode", "google_serp", "google_shopping"]
+      if @api_client.config.client_side_validation && opts[:'engines'] && !opts[:'engines'].all? { |item| allowable_values.include?(item) }
+        fail ArgumentError, "invalid value for \"engines\", must include one of #{allowable_values}"
+      end
+      allowable_values = ["active", "paused"]
+      if @api_client.config.client_side_validation && opts[:'status'] && !allowable_values.include?(opts[:'status'])
+        fail ArgumentError, "invalid value for \"status\", must be one of #{allowable_values}"
+      end
+      allowable_values = ["daily", "weekly", "monthly"]
+      if @api_client.config.client_side_validation && opts[:'check_frequencies'] && !opts[:'check_frequencies'].all? { |item| allowable_values.include?(item) }
+        fail ArgumentError, "invalid value for \"check_frequencies\", must include one of #{allowable_values}"
+      end
+      if @api_client.config.client_side_validation && !opts[:'search'].nil? && opts[:'search'].to_s.length > 100
+        fail ArgumentError, 'invalid value for "opts[:"search"]" when calling AnalyticsApi.list_keyword_listings, the character length must be smaller than or equal to 100.'
+      end
+
+      allowable_values = ["keyword", "variantCount", "lastCheckedAt", "statusSummary", "positivityIndex", "shareOfVoice", "avgMentionPosition", "avgLinkPosition", "mentionPositionStability", "avgSerpPosition", "avgShoppingPosition"]
+      if @api_client.config.client_side_validation && opts[:'sort_by'] && !allowable_values.include?(opts[:'sort_by'])
+        fail ArgumentError, "invalid value for \"sort_by\", must be one of #{allowable_values}"
+      end
+      allowable_values = ["asc", "desc"]
+      if @api_client.config.client_side_validation && opts[:'sort_order'] && !allowable_values.include?(opts[:'sort_order'])
+        fail ArgumentError, "invalid value for \"sort_order\", must be one of #{allowable_values}"
+      end
+      if @api_client.config.client_side_validation && !opts[:'limit'].nil? && opts[:'limit'] > 100
+        fail ArgumentError, 'invalid value for "opts[:"limit"]" when calling AnalyticsApi.list_keyword_listings, must be smaller than or equal to 100.'
+      end
+
+      if @api_client.config.client_side_validation && !opts[:'limit'].nil? && opts[:'limit'] < 1
+        fail ArgumentError, 'invalid value for "opts[:"limit"]" when calling AnalyticsApi.list_keyword_listings, must be greater than or equal to 1.'
+      end
+
+      if @api_client.config.client_side_validation && !opts[:'offset'].nil? && opts[:'offset'] < 0
+        fail ArgumentError, 'invalid value for "opts[:"offset"]" when calling AnalyticsApi.list_keyword_listings, must be greater than or equal to 0.'
+      end
+
+      # resource path
+      local_var_path = '/api/v1/organizations/{organizationId}/projects/{projectId}/keyword-listings'.sub('{organizationId}', CGI.escape(organization_id.to_s)).sub('{projectId}', CGI.escape(project_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'dateFrom'] = date_from
+      query_params[:'dateTo'] = date_to
+      query_params[:'engines'] = @api_client.build_collection_param(opts[:'engines'], :multi) if !opts[:'engines'].nil?
+      query_params[:'countries'] = @api_client.build_collection_param(opts[:'countries'], :multi) if !opts[:'countries'].nil?
+      query_params[:'queryClusterIds'] = @api_client.build_collection_param(opts[:'query_cluster_ids'], :multi) if !opts[:'query_cluster_ids'].nil?
+      query_params[:'includeUngroupedQueries'] = opts[:'include_ungrouped_queries'] if !opts[:'include_ungrouped_queries'].nil?
+      query_params[:'status'] = opts[:'status'] if !opts[:'status'].nil?
+      query_params[:'checkFrequencies'] = @api_client.build_collection_param(opts[:'check_frequencies'], :multi) if !opts[:'check_frequencies'].nil?
+      query_params[:'nPasses'] = @api_client.build_collection_param(opts[:'n_passes'], :multi) if !opts[:'n_passes'].nil?
+      query_params[:'search'] = opts[:'search'] if !opts[:'search'].nil?
+      query_params[:'sortBy'] = opts[:'sort_by'] if !opts[:'sort_by'].nil?
+      query_params[:'sortOrder'] = opts[:'sort_order'] if !opts[:'sort_order'].nil?
+      query_params[:'limit'] = opts[:'limit'] if !opts[:'limit'].nil?
+      query_params[:'offset'] = opts[:'offset'] if !opts[:'offset'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'ListKeywordListings200Response'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ApiKey']
+
+      new_options = opts.merge(
+        :operation => :"AnalyticsApi.list_keyword_listings",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AnalyticsApi#list_keyword_listings\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+  end
+end