mencoro 1.0.1 → 2.0.0

data/lib/mencoro/api/analytics_api.rb

@@ -1,7 +1,7 @@
 =begin
 #Mencoro API
 
-#Public API for Mencoro customers. Authenticate with an API key: `Authorization: Bearer mencoro_sk_...`.
+#Public API for Mencoro customers. Authenticate with an API key: `Authorization: Bearer mencoro_sk_...`. Every write operation requires an `Idempotency-Key` header: a retry carrying the same key and body within 30 days is answered from the stored result without running again; after 30 days the key is forgotten and a retry runs as a new operation.
 
 The version of the OpenAPI document: 1.0.0
 Contact: support@mencoro.com
@@ -89,7 +89,7 @@ module Mencoro
     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.
+    # 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, claude, 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.
@@ -99,14 +99,14 @@ module Mencoro
     # @option opts [String] :group_by Grain of the roll-up: \"domain\" by host, \"page\" 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]
+    # @return [CitedSourcesResponse]
     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
+      data, _status_code, _headers = get_cited_sources_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      data
     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.
+    # 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, claude, 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.
@@ -116,7 +116,7 @@ module Mencoro
     # @option opts [String] :group_by Grain of the roll-up: \"domain\" by host, \"page\" 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
+    # @return [Array<(CitedSourcesResponse, Integer, Hash)>] CitedSourcesResponse data, 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 ...'
@@ -137,7 +137,7 @@ module Mencoro
       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"]
+      allowable_values = ["chatgpt", "claude", "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
@@ -171,6 +171,8 @@ module Mencoro
 
       # 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] || {}
@@ -179,7 +181,7 @@ module Mencoro
       post_body = opts[:debug_body]
 
       # return_type
-      return_type = opts[:debug_return_type]
+      return_type = opts[:debug_return_type] || 'CitedSourcesResponse'
 
       # auth_names
       auth_names = opts[:debug_auth_names] || ['ApiKey']
@@ -211,11 +213,11 @@ module Mencoro
     # @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]
+    # @option opts [Boolean] :include_ungrouped_queries Sent alone, returns only the ungrouped row: the tracked queries that belong to no cluster (refused if there are none). Sent with queryClusterIds, adds that row to those clusters. Omit both for every cluster plus the ungrouped row. (default to false)
+    # @return [ProjectRankTrackingClusterBreakdown]
     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
+      data, _status_code, _headers = get_cluster_breakdown_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      data
     end
 
     # Rank-tracking metrics per keyword cluster
@@ -228,8 +230,8 @@ module Mencoro
     # @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
+    # @option opts [Boolean] :include_ungrouped_queries Sent alone, returns only the ungrouped row: the tracked queries that belong to no cluster (refused if there are none). Sent with queryClusterIds, adds that row to those clusters. Omit both for every cluster plus the ungrouped row. (default to false)
+    # @return [Array<(ProjectRankTrackingClusterBreakdown, Integer, Hash)>] ProjectRankTrackingClusterBreakdown data, 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 ...'
@@ -250,7 +252,7 @@ module Mencoro
       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"]
+      allowable_values = ["chatgpt", "claude", "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
@@ -268,6 +270,8 @@ module Mencoro
 
       # 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] || {}
@@ -276,7 +280,7 @@ module Mencoro
       post_body = opts[:debug_body]
 
       # return_type
-      return_type = opts[:debug_return_type]
+      return_type = opts[:debug_return_type] || 'ProjectRankTrackingClusterBreakdown'
 
       # auth_names
       auth_names = opts[:debug_auth_names] || ['ApiKey']
@@ -308,10 +312,10 @@ module Mencoro
     # @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]
+    # @return [CompetitorCoOccurrenceResponse]
     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
+      data, _status_code, _headers = get_competitor_co_occurrence_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      data
     end
 
     # Head-to-head record of the brand against each tracked competitor
@@ -324,7 +328,7 @@ module Mencoro
     # @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
+    # @return [Array<(CompetitorCoOccurrenceResponse, Integer, Hash)>] CompetitorCoOccurrenceResponse data, 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 ...'
@@ -345,7 +349,7 @@ module Mencoro
       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"]
+      allowable_values = ["chatgpt", "claude", "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
@@ -362,6 +366,8 @@ module Mencoro
 
       # 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] || {}
@@ -370,7 +376,7 @@ module Mencoro
       post_body = opts[:debug_body]
 
       # return_type
-      return_type = opts[:debug_return_type]
+      return_type = opts[:debug_return_type] || 'CompetitorCoOccurrenceResponse'
 
       # auth_names
       auth_names = opts[:debug_auth_names] || ['ApiKey']
@@ -393,7 +399,7 @@ module Mencoro
     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.
+    # 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). 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: tracked competitors, untracked competitors and unrelated brands are all excluded (mentions stored before the relation was recorded count as the brand, as they do in Share of Voice). Only mentions inside the answer text are counted — a citation of the brand's URL is not a mention here. Each count is a raw number of stored mentions: when a query runs several passes a day, every pass adds its own. The counts therefore show the composition of the brand's mentions but are not the inputs of the Share of Voice score, which averages each check over its passes and also weights cited links. 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.
@@ -401,14 +407,14 @@ module Mencoro
     # @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]
+    # @return [ProjectMentionMixResponse]
     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
+      data, _status_code, _headers = get_mention_mix_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      data
     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.
+    # 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). 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: tracked competitors, untracked competitors and unrelated brands are all excluded (mentions stored before the relation was recorded count as the brand, as they do in Share of Voice). Only mentions inside the answer text are counted — a citation of the brand&#39;s URL is not a mention here. Each count is a raw number of stored mentions: when a query runs several passes a day, every pass adds its own. The counts therefore show the composition of the brand&#39;s mentions but are not the inputs of the Share of Voice score, which averages each check over its passes and also weights cited links. 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.
@@ -416,7 +422,7 @@ module Mencoro
     # @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
+    # @return [Array<(ProjectMentionMixResponse, Integer, Hash)>] ProjectMentionMixResponse data, 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 ...'
@@ -437,7 +443,7 @@ module Mencoro
       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"]
+      allowable_values = ["chatgpt", "claude", "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
@@ -453,6 +459,8 @@ module Mencoro
 
       # 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] || {}
@@ -461,7 +469,7 @@ module Mencoro
       post_body = opts[:debug_body]
 
       # return_type
-      return_type = opts[:debug_return_type]
+      return_type = opts[:debug_return_type] || 'ProjectMentionMixResponse'
 
       # auth_names
       auth_names = opts[:debug_auth_names] || ['ApiKey']
@@ -484,7 +492,7 @@ module Mencoro
     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.
+    # 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 the brand's own mention counts by type, tone and qualifier 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.
@@ -498,14 +506,14 @@ module Mencoro
     # @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]
+    # @return [ProjectMentionSamplesResponse]
     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
+      data, _status_code, _headers = get_mention_samples_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      data
     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.
+    # 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 the brand&#39;s own mention counts by type, tone and qualifier 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.
@@ -519,7 +527,7 @@ module Mencoro
     # @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
+    # @return [Array<(ProjectMentionSamplesResponse, Integer, Hash)>] ProjectMentionSamplesResponse data, 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 ...'
@@ -540,7 +548,7 @@ module Mencoro
       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"]
+      allowable_values = ["chatgpt", "claude", "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
@@ -596,7 +604,7 @@ module Mencoro
       post_body = opts[:debug_body]
 
       # return_type
-      return_type = opts[:debug_return_type]
+      return_type = opts[:debug_return_type] || 'ProjectMentionSamplesResponse'
 
       # auth_names
       auth_names = opts[:debug_auth_names] || ['ApiKey']
@@ -676,7 +684,7 @@ module Mencoro
     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.
+    # Minimum role: viewer. One row per active project the caller can access — 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. For a member restricted to selected projects, the rows and every aggregate figure cover those projects only. 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]
@@ -686,7 +694,7 @@ module Mencoro
     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.
+    # Minimum role: viewer. One row per active project the caller can access — 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. For a member restricted to selected projects, the rows and every aggregate figure cover those projects only. 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
@@ -739,7 +747,7 @@ module Mencoro
     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.
+    # Minimum role: viewer. The project overview over a date window: share of voice (own and per competitor), mention / SERP / shopping rates, average 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, signed so that POSITIVE always means improved: for a position or a stability spread a positive trend means the number went down, for a rate or score it means the number went up. 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.
@@ -748,15 +756,15 @@ module Mencoro
     # @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]
+    # @option opts [Boolean] :include_ungrouped_queries Sent alone, restricts to tracked queries that belong to no cluster (refused if there are none). Sent with queryClusterIds, adds them to those clusters. Omit both for all tracked queries. (default to false)
+    # @return [ProjectRankTrackingStats]
     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
+      data, _status_code, _headers = get_project_metrics_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      data
     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.
+    # Minimum role: viewer. The project overview over a date window: share of voice (own and per competitor), mention / SERP / shopping rates, average 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, signed so that POSITIVE always means improved: for a position or a stability spread a positive trend means the number went down, for a rate or score it means the number went up. 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.
@@ -765,8 +773,8 @@ module Mencoro
     # @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
+    # @option opts [Boolean] :include_ungrouped_queries Sent alone, restricts to tracked queries that belong to no cluster (refused if there are none). Sent with queryClusterIds, adds them to those clusters. Omit both for all tracked queries. (default to false)
+    # @return [Array<(ProjectRankTrackingStats, Integer, Hash)>] ProjectRankTrackingStats data, 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 ...'
@@ -787,7 +795,7 @@ module Mencoro
       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"]
+      allowable_values = ["chatgpt", "claude", "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
@@ -805,6 +813,8 @@ module Mencoro
 
       # 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] || {}
@@ -813,7 +823,7 @@ module Mencoro
       post_body = opts[:debug_body]
 
       # return_type
-      return_type = opts[:debug_return_type]
+      return_type = opts[:debug_return_type] || 'ProjectRankTrackingStats'
 
       # auth_names
       auth_names = opts[:debug_auth_names] || ['ApiKey']
@@ -845,11 +855,11 @@ module Mencoro
     # @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]
+    # @option opts [Boolean] :include_ungrouped_queries Sent alone, restricts to tracked queries that belong to no cluster (refused if there are none). Sent with queryClusterIds, adds them to those clusters. Omit both for all tracked queries. (default to false)
+    # @return [ProjectSentimentBreakdown]
     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
+      data, _status_code, _headers = get_project_sentiment_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      data
     end
 
     # Sentiment breakdown of a project brand mentions
@@ -862,8 +872,8 @@ module Mencoro
     # @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
+    # @option opts [Boolean] :include_ungrouped_queries Sent alone, restricts to tracked queries that belong to no cluster (refused if there are none). Sent with queryClusterIds, adds them to those clusters. Omit both for all tracked queries. (default to false)
+    # @return [Array<(ProjectSentimentBreakdown, Integer, Hash)>] ProjectSentimentBreakdown data, 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 ...'
@@ -884,7 +894,7 @@ module Mencoro
       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"]
+      allowable_values = ["chatgpt", "claude", "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
@@ -902,6 +912,8 @@ module Mencoro
 
       # 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] || {}
@@ -910,7 +922,7 @@ module Mencoro
       post_body = opts[:debug_body]
 
       # return_type
-      return_type = opts[:debug_return_type]
+      return_type = opts[:debug_return_type] || 'ProjectSentimentBreakdown'
 
       # auth_names
       auth_names = opts[:debug_auth_names] || ['ApiKey']
@@ -943,12 +955,12 @@ module Mencoro
     # @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 [Boolean] :include_ungrouped_queries Sent alone, restricts to tracked queries that belong to no cluster (refused if there are none). Sent with queryClusterIds, adds them to those clusters. Omit both for all tracked queries. (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]
+    # @return [ProjectRankTrackingTimeSeries]
     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
+      data, _status_code, _headers = get_project_time_series_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      data
     end
 
     # Rank-tracking metrics of a project over time
@@ -962,9 +974,9 @@ module Mencoro
     # @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 [Boolean] :include_ungrouped_queries Sent alone, restricts to tracked queries that belong to no cluster (refused if there are none). Sent with queryClusterIds, adds them to those clusters. Omit both for all tracked queries. (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
+    # @return [Array<(ProjectRankTrackingTimeSeries, Integer, Hash)>] ProjectRankTrackingTimeSeries data, 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 ...'
@@ -989,7 +1001,7 @@ module Mencoro
       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"]
+      allowable_values = ["chatgpt", "claude", "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
@@ -1009,6 +1021,8 @@ module Mencoro
 
       # 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] || {}
@@ -1017,7 +1031,7 @@ module Mencoro
       post_body = opts[:debug_body]
 
       # return_type
-      return_type = opts[:debug_return_type]
+      return_type = opts[:debug_return_type] || 'ProjectRankTrackingTimeSeries'
 
       # auth_names
       auth_names = opts[:debug_auth_names] || ['ApiKey']
@@ -1052,10 +1066,10 @@ module Mencoro
     # @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]
+    # @return [TrackedQueryMoversResponse]
     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
+      data, _status_code, _headers = get_query_movers_with_http_info(organization_id, project_id, date_from, date_to, opts)
+      data
     end
 
     # Tracked queries ranked by how much a metric moved
@@ -1071,7 +1085,7 @@ module Mencoro
     # @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
+    # @return [Array<(TrackedQueryMoversResponse, Integer, Hash)>] TrackedQueryMoversResponse data, 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 ...'
@@ -1092,7 +1106,7 @@ module Mencoro
       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"]
+      allowable_values = ["chatgpt", "claude", "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
@@ -1132,6 +1146,8 @@ module Mencoro
 
       # 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] || {}
@@ -1140,7 +1156,7 @@ module Mencoro
       post_body = opts[:debug_body]
 
       # return_type
-      return_type = opts[:debug_return_type]
+      return_type = opts[:debug_return_type] || 'TrackedQueryMoversResponse'
 
       # auth_names
       auth_names = opts[:debug_auth_names] || ['ApiKey']
@@ -1163,7 +1179,7 @@ module Mencoro
     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.
+    # 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 score averages each check over its passes and also weights cited links, so applying these constants to the raw counts of the mention mix endpoint does not reproduce it. Every value is always present and is never null.
     # @param organization_id [String] 
     # @param project_id [String] 
     # @param [Hash] opts the optional parameters
@@ -1174,7 +1190,7 @@ module Mencoro
     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.
+    # 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 score averages each check over its passes and also weights cited links, so applying these constants to the raw counts of the mention mix endpoint does not reproduce it. Every value is always present and is never null.
     # @param organization_id [String] 
     # @param project_id [String] 
     # @param [Hash] opts the optional parameters
@@ -1232,7 +1248,7 @@ module Mencoro
     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.
+    # 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 bucket appears only when something was matched for the query in it; when only competitors were, the brand's metrics are all null, so a brand that was not mentioned reads as a null shareOfVoice, not as 0. shareOfVoice is also null, even with the brand mentioned, when no tracked competitor carried any mention weight on any day of the bucket: it is a share against tracked competitors, and a weekly or monthly value averages only the days where it could be computed. 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.
@@ -1241,14 +1257,14 @@ module Mencoro
     # @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]
+    # @return [TrackedQueryRankTrackingTimeSeries]
     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
+      data, _status_code, _headers = get_tracked_query_time_series_with_http_info(organization_id, project_id, tracked_query_id, date_from, date_to, opts)
+      data
     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.
+    # 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 bucket appears only when something was matched for the query in it; when only competitors were, the brand&#39;s metrics are all null, so a brand that was not mentioned reads as a null shareOfVoice, not as 0. shareOfVoice is also null, even with the brand mentioned, when no tracked competitor carried any mention weight on any day of the bucket: it is a share against tracked competitors, and a weekly or monthly value averages only the days where it could be computed. 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.
@@ -1257,7 +1273,7 @@ module Mencoro
     # @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
+    # @return [Array<(TrackedQueryRankTrackingTimeSeries, Integer, Hash)>] TrackedQueryRankTrackingTimeSeries data, 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 ...'
@@ -1298,6 +1314,8 @@ module Mencoro
 
       # 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] || {}
@@ -1306,7 +1324,7 @@ module Mencoro
       post_body = opts[:debug_body]
 
       # return_type
-      return_type = opts[:debug_return_type]
+      return_type = opts[:debug_return_type] || 'TrackedQueryRankTrackingTimeSeries'
 
       # auth_names
       auth_names = opts[:debug_auth_names] || ['ApiKey']
@@ -1407,7 +1425,7 @@ module Mencoro
     # @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 [Boolean] :include_ungrouped_queries Sent alone, restricts to keywords with variants that belong to no cluster (refused if there are none). Sent with queryClusterIds, adds them to those clusters. Omit both for all keywords. (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.
@@ -1432,7 +1450,7 @@ module Mencoro
     # @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 [Boolean] :include_ungrouped_queries Sent alone, restricts to keywords with variants that belong to no cluster (refused if there are none). Sent with queryClusterIds, adds them to those clusters. Omit both for all keywords. (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.
@@ -1462,7 +1480,7 @@ module Mencoro
       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"]
+      allowable_values = ["chatgpt", "claude", "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