mencoro 1.0.1 → 2.0.1

data/docs/AnalyticsApi.md

@@ -95,11 +95,11 @@ end
 
 ## get_cited_sources
 
-> get_cited_sources(organization_id, project_id, date_from, date_to, opts)
+> <CitedSourcesResponse> get_cited_sources(organization_id, project_id, date_from, date_to, opts)
 
 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.
 
 ### Examples
 
@@ -126,7 +126,8 @@ opts = {
 
 begin
   # Domains and pages the AI answers cited
-  api_instance.get_cited_sources(organization_id, project_id, date_from, date_to, opts)
+  result = api_instance.get_cited_sources(organization_id, project_id, date_from, date_to, opts)
+  p result
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_cited_sources: #{e}"
 end
@@ -134,9 +135,9 @@ end
 
 #### Using the get_cited_sources_with_http_info variant
 
-This returns an Array which contains the response data (`nil` in this case), status code and headers.
+This returns an Array which contains the response data, status code and headers.
 
-> <Array(nil, Integer, Hash)> get_cited_sources_with_http_info(organization_id, project_id, date_from, date_to, opts)
+> <Array(<CitedSourcesResponse>, Integer, Hash)> get_cited_sources_with_http_info(organization_id, project_id, date_from, date_to, opts)
 
 ```ruby
 begin
@@ -144,7 +145,7 @@ begin
   data, status_code, headers = api_instance.get_cited_sources_with_http_info(organization_id, project_id, date_from, date_to, opts)
   p status_code # => 2xx
   p headers # => { ... }
-  p data # => nil
+  p data # => <CitedSourcesResponse>
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_cited_sources_with_http_info: #{e}"
 end
@@ -165,7 +166,7 @@ end
 
 ### Return type
 
-nil (empty response body)
+[**CitedSourcesResponse**](CitedSourcesResponse.md)
 
 ### Authorization
 
@@ -174,12 +175,12 @@ nil (empty response body)
 ### HTTP request headers
 
 - **Content-Type**: Not defined
-- **Accept**: Not defined
+- **Accept**: application/json
 
 
 ## get_cluster_breakdown
 
-> get_cluster_breakdown(organization_id, project_id, date_from, date_to, opts)
+> <ProjectRankTrackingClusterBreakdown> get_cluster_breakdown(organization_id, project_id, date_from, date_to, opts)
 
 Rank-tracking metrics per keyword cluster
 
@@ -205,12 +206,13 @@ opts = {
   engines: ['chatgpt'], # Array<String> | Repeatable, or comma-separated.
   countries: ['inner_example'], # Array<String> | ISO-3166 alpha-2 codes or English names. Must be configured on the project.
   query_cluster_ids: ['inner_example'], # Array<String> | Restrict to these clusters. Each must belong to the project.
-  include_ungrouped_queries: true # Boolean | Sent alone, returns only the ungrouped bucket rather than adding it to every cluster.
+  include_ungrouped_queries: true # Boolean | 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.
 }
 
 begin
   # Rank-tracking metrics per keyword cluster
-  api_instance.get_cluster_breakdown(organization_id, project_id, date_from, date_to, opts)
+  result = api_instance.get_cluster_breakdown(organization_id, project_id, date_from, date_to, opts)
+  p result
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_cluster_breakdown: #{e}"
 end
@@ -218,9 +220,9 @@ end
 
 #### Using the get_cluster_breakdown_with_http_info variant
 
-This returns an Array which contains the response data (`nil` in this case), status code and headers.
+This returns an Array which contains the response data, status code and headers.
 
-> <Array(nil, Integer, Hash)> get_cluster_breakdown_with_http_info(organization_id, project_id, date_from, date_to, opts)
+> <Array(<ProjectRankTrackingClusterBreakdown>, Integer, Hash)> get_cluster_breakdown_with_http_info(organization_id, project_id, date_from, date_to, opts)
 
 ```ruby
 begin
@@ -228,7 +230,7 @@ begin
   data, status_code, headers = api_instance.get_cluster_breakdown_with_http_info(organization_id, project_id, date_from, date_to, opts)
   p status_code # => 2xx
   p headers # => { ... }
-  p data # => nil
+  p data # => <ProjectRankTrackingClusterBreakdown>
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_cluster_breakdown_with_http_info: #{e}"
 end
@@ -245,11 +247,11 @@ end
 | **engines** | [**Array&lt;String&gt;**](String.md) | Repeatable, or comma-separated. | [optional] |
 | **countries** | [**Array&lt;String&gt;**](String.md) | ISO-3166 alpha-2 codes or English names. Must be configured on the project. | [optional] |
 | **query_cluster_ids** | [**Array&lt;String&gt;**](String.md) | Restrict to these clusters. Each must belong to the project. | [optional] |
-| **include_ungrouped_queries** | **Boolean** | Sent alone, returns only the ungrouped bucket rather than adding it to every cluster. | [optional][default to false] |
+| **include_ungrouped_queries** | **Boolean** | 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. | [optional][default to false] |
 
 ### Return type
 
-nil (empty response body)
+[**ProjectRankTrackingClusterBreakdown**](ProjectRankTrackingClusterBreakdown.md)
 
 ### Authorization
 
@@ -258,12 +260,12 @@ nil (empty response body)
 ### HTTP request headers
 
 - **Content-Type**: Not defined
-- **Accept**: Not defined
+- **Accept**: application/json
 
 
 ## get_competitor_co_occurrence
 
-> get_competitor_co_occurrence(organization_id, project_id, date_from, date_to, opts)
+> <CompetitorCoOccurrenceResponse> get_competitor_co_occurrence(organization_id, project_id, date_from, date_to, opts)
 
 Head-to-head record of the brand against each tracked competitor
 
@@ -293,7 +295,8 @@ opts = {
 
 begin
   # Head-to-head record of the brand against each tracked competitor
-  api_instance.get_competitor_co_occurrence(organization_id, project_id, date_from, date_to, opts)
+  result = api_instance.get_competitor_co_occurrence(organization_id, project_id, date_from, date_to, opts)
+  p result
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_competitor_co_occurrence: #{e}"
 end
@@ -301,9 +304,9 @@ end
 
 #### Using the get_competitor_co_occurrence_with_http_info variant
 
-This returns an Array which contains the response data (`nil` in this case), status code and headers.
+This returns an Array which contains the response data, status code and headers.
 
-> <Array(nil, Integer, Hash)> get_competitor_co_occurrence_with_http_info(organization_id, project_id, date_from, date_to, opts)
+> <Array(<CompetitorCoOccurrenceResponse>, Integer, Hash)> get_competitor_co_occurrence_with_http_info(organization_id, project_id, date_from, date_to, opts)
 
 ```ruby
 begin
@@ -311,7 +314,7 @@ begin
   data, status_code, headers = api_instance.get_competitor_co_occurrence_with_http_info(organization_id, project_id, date_from, date_to, opts)
   p status_code # => 2xx
   p headers # => { ... }
-  p data # => nil
+  p data # => <CompetitorCoOccurrenceResponse>
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_competitor_co_occurrence_with_http_info: #{e}"
 end
@@ -331,7 +334,7 @@ end
 
 ### Return type
 
-nil (empty response body)
+[**CompetitorCoOccurrenceResponse**](CompetitorCoOccurrenceResponse.md)
 
 ### Authorization
 
@@ -340,16 +343,16 @@ nil (empty response body)
 ### HTTP request headers
 
 - **Content-Type**: Not defined
-- **Accept**: Not defined
+- **Accept**: application/json
 
 
 ## get_mention_mix
 
-> get_mention_mix(organization_id, project_id, date_from, date_to, opts)
+> <ProjectMentionMixResponse> get_mention_mix(organization_id, project_id, date_from, date_to, opts)
 
 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.
 
 ### Examples
 
@@ -374,7 +377,8 @@ opts = {
 
 begin
   # Composition of a project brand mentions in AI answers
-  api_instance.get_mention_mix(organization_id, project_id, date_from, date_to, opts)
+  result = api_instance.get_mention_mix(organization_id, project_id, date_from, date_to, opts)
+  p result
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_mention_mix: #{e}"
 end
@@ -382,9 +386,9 @@ end
 
 #### Using the get_mention_mix_with_http_info variant
 
-This returns an Array which contains the response data (`nil` in this case), status code and headers.
+This returns an Array which contains the response data, status code and headers.
 
-> <Array(nil, Integer, Hash)> get_mention_mix_with_http_info(organization_id, project_id, date_from, date_to, opts)
+> <Array(<ProjectMentionMixResponse>, Integer, Hash)> get_mention_mix_with_http_info(organization_id, project_id, date_from, date_to, opts)
 
 ```ruby
 begin
@@ -392,7 +396,7 @@ begin
   data, status_code, headers = api_instance.get_mention_mix_with_http_info(organization_id, project_id, date_from, date_to, opts)
   p status_code # => 2xx
   p headers # => { ... }
-  p data # => nil
+  p data # => <ProjectMentionMixResponse>
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_mention_mix_with_http_info: #{e}"
 end
@@ -411,7 +415,7 @@ end
 
 ### Return type
 
-nil (empty response body)
+[**ProjectMentionMixResponse**](ProjectMentionMixResponse.md)
 
 ### Authorization
 
@@ -420,16 +424,16 @@ nil (empty response body)
 ### HTTP request headers
 
 - **Content-Type**: Not defined
-- **Accept**: Not defined
+- **Accept**: application/json
 
 
 ## get_mention_samples
 
-> get_mention_samples(organization_id, project_id, date_from, date_to, opts)
+> <ProjectMentionSamplesResponse> get_mention_samples(organization_id, project_id, date_from, date_to, opts)
 
 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.
 
 ### Examples
 
@@ -460,7 +464,8 @@ opts = {
 
 begin
   # Sample of the raw AI mention texts of a project
-  api_instance.get_mention_samples(organization_id, project_id, date_from, date_to, opts)
+  result = api_instance.get_mention_samples(organization_id, project_id, date_from, date_to, opts)
+  p result
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_mention_samples: #{e}"
 end
@@ -468,9 +473,9 @@ end
 
 #### Using the get_mention_samples_with_http_info variant
 
-This returns an Array which contains the response data (`nil` in this case), status code and headers.
+This returns an Array which contains the response data, status code and headers.
 
-> <Array(nil, Integer, Hash)> get_mention_samples_with_http_info(organization_id, project_id, date_from, date_to, opts)
+> <Array(<ProjectMentionSamplesResponse>, Integer, Hash)> get_mention_samples_with_http_info(organization_id, project_id, date_from, date_to, opts)
 
 ```ruby
 begin
@@ -478,7 +483,7 @@ begin
   data, status_code, headers = api_instance.get_mention_samples_with_http_info(organization_id, project_id, date_from, date_to, opts)
   p status_code # => 2xx
   p headers # => { ... }
-  p data # => nil
+  p data # => <ProjectMentionSamplesResponse>
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_mention_samples_with_http_info: #{e}"
 end
@@ -503,7 +508,7 @@ end
 
 ### Return type
 
-nil (empty response body)
+[**ProjectMentionSamplesResponse**](ProjectMentionSamplesResponse.md)
 
 ### Authorization
 
@@ -587,7 +592,7 @@ This endpoint does not need any parameter.
 
 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.
 
 ### Examples
 
@@ -652,11 +657,11 @@ end
 
 ## get_project_metrics
 
-> get_project_metrics(organization_id, project_id, date_from, date_to, opts)
+> <ProjectRankTrackingStats> get_project_metrics(organization_id, project_id, date_from, date_to, opts)
 
 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.
 
 ### Examples
 
@@ -678,12 +683,13 @@ opts = {
   engines: ['chatgpt'], # Array<String> | Repeatable, or comma-separated.
   countries: ['inner_example'], # Array<String> | ISO-3166 alpha-2 codes or English names. Must be configured on the project.
   query_cluster_ids: ['inner_example'], # Array<String> | Restrict to these keyword clusters. Each must belong to this project.
-  include_ungrouped_queries: true # Boolean | Only meaningful together with queryClusterIds: also counts the tracked queries that belong to no cluster.
+  include_ungrouped_queries: true # Boolean | 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.
 }
 
 begin
   # Headline visibility metrics of a project
-  api_instance.get_project_metrics(organization_id, project_id, date_from, date_to, opts)
+  result = api_instance.get_project_metrics(organization_id, project_id, date_from, date_to, opts)
+  p result
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_project_metrics: #{e}"
 end
@@ -691,9 +697,9 @@ end
 
 #### Using the get_project_metrics_with_http_info variant
 
-This returns an Array which contains the response data (`nil` in this case), status code and headers.
+This returns an Array which contains the response data, status code and headers.
 
-> <Array(nil, Integer, Hash)> get_project_metrics_with_http_info(organization_id, project_id, date_from, date_to, opts)
+> <Array(<ProjectRankTrackingStats>, Integer, Hash)> get_project_metrics_with_http_info(organization_id, project_id, date_from, date_to, opts)
 
 ```ruby
 begin
@@ -701,7 +707,7 @@ begin
   data, status_code, headers = api_instance.get_project_metrics_with_http_info(organization_id, project_id, date_from, date_to, opts)
   p status_code # => 2xx
   p headers # => { ... }
-  p data # => nil
+  p data # => <ProjectRankTrackingStats>
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_project_metrics_with_http_info: #{e}"
 end
@@ -718,11 +724,11 @@ end
 | **engines** | [**Array&lt;String&gt;**](String.md) | Repeatable, or comma-separated. | [optional] |
 | **countries** | [**Array&lt;String&gt;**](String.md) | ISO-3166 alpha-2 codes or English names. Must be configured on the project. | [optional] |
 | **query_cluster_ids** | [**Array&lt;String&gt;**](String.md) | Restrict to these keyword clusters. Each must belong to this project. | [optional] |
-| **include_ungrouped_queries** | **Boolean** | Only meaningful together with queryClusterIds: also counts the tracked queries that belong to no cluster. | [optional][default to false] |
+| **include_ungrouped_queries** | **Boolean** | 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. | [optional][default to false] |
 
 ### Return type
 
-nil (empty response body)
+[**ProjectRankTrackingStats**](ProjectRankTrackingStats.md)
 
 ### Authorization
 
@@ -731,12 +737,12 @@ nil (empty response body)
 ### HTTP request headers
 
 - **Content-Type**: Not defined
-- **Accept**: Not defined
+- **Accept**: application/json
 
 
 ## get_project_sentiment
 
-> get_project_sentiment(organization_id, project_id, date_from, date_to, opts)
+> <ProjectSentimentBreakdown> get_project_sentiment(organization_id, project_id, date_from, date_to, opts)
 
 Sentiment breakdown of a project brand mentions
 
@@ -762,12 +768,13 @@ opts = {
   engines: ['chatgpt'], # Array<String> | Repeatable, or comma-separated.
   countries: ['inner_example'], # Array<String> | ISO-3166 alpha-2 codes or English names. Must be configured on the project.
   query_cluster_ids: ['inner_example'], # Array<String> | 
-  include_ungrouped_queries: true # Boolean | 
+  include_ungrouped_queries: true # Boolean | 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.
 }
 
 begin
   # Sentiment breakdown of a project brand mentions
-  api_instance.get_project_sentiment(organization_id, project_id, date_from, date_to, opts)
+  result = api_instance.get_project_sentiment(organization_id, project_id, date_from, date_to, opts)
+  p result
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_project_sentiment: #{e}"
 end
@@ -775,9 +782,9 @@ end
 
 #### Using the get_project_sentiment_with_http_info variant
 
-This returns an Array which contains the response data (`nil` in this case), status code and headers.
+This returns an Array which contains the response data, status code and headers.
 
-> <Array(nil, Integer, Hash)> get_project_sentiment_with_http_info(organization_id, project_id, date_from, date_to, opts)
+> <Array(<ProjectSentimentBreakdown>, Integer, Hash)> get_project_sentiment_with_http_info(organization_id, project_id, date_from, date_to, opts)
 
 ```ruby
 begin
@@ -785,7 +792,7 @@ begin
   data, status_code, headers = api_instance.get_project_sentiment_with_http_info(organization_id, project_id, date_from, date_to, opts)
   p status_code # => 2xx
   p headers # => { ... }
-  p data # => nil
+  p data # => <ProjectSentimentBreakdown>
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_project_sentiment_with_http_info: #{e}"
 end
@@ -802,11 +809,11 @@ end
 | **engines** | [**Array&lt;String&gt;**](String.md) | Repeatable, or comma-separated. | [optional] |
 | **countries** | [**Array&lt;String&gt;**](String.md) | ISO-3166 alpha-2 codes or English names. Must be configured on the project. | [optional] |
 | **query_cluster_ids** | [**Array&lt;String&gt;**](String.md) |  | [optional] |
-| **include_ungrouped_queries** | **Boolean** |  | [optional][default to false] |
+| **include_ungrouped_queries** | **Boolean** | 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. | [optional][default to false] |
 
 ### Return type
 
-nil (empty response body)
+[**ProjectSentimentBreakdown**](ProjectSentimentBreakdown.md)
 
 ### Authorization
 
@@ -815,12 +822,12 @@ nil (empty response body)
 ### HTTP request headers
 
 - **Content-Type**: Not defined
-- **Accept**: Not defined
+- **Accept**: application/json
 
 
 ## get_project_time_series
 
-> get_project_time_series(organization_id, project_id, date_from, date_to, opts)
+> <ProjectRankTrackingTimeSeries> get_project_time_series(organization_id, project_id, date_from, date_to, opts)
 
 Rank-tracking metrics of a project over time
 
@@ -847,13 +854,14 @@ opts = {
   engines: ['chatgpt'], # Array<String> | Repeatable, or comma-separated.
   countries: ['inner_example'], # Array<String> | ISO-3166 alpha-2 codes or English names. Must be configured on the project.
   query_cluster_ids: ['inner_example'], # Array<String> | 
-  include_ungrouped_queries: true, # Boolean | 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.
+  include_ungrouped_queries: true, # Boolean | 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.
   competitor_ids: ['inner_example'] # Array<String> | Repeatable, or comma-separated. Each id adds one series under the competitors map of every point.
 }
 
 begin
   # Rank-tracking metrics of a project over time
-  api_instance.get_project_time_series(organization_id, project_id, date_from, date_to, opts)
+  result = api_instance.get_project_time_series(organization_id, project_id, date_from, date_to, opts)
+  p result
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_project_time_series: #{e}"
 end
@@ -861,9 +869,9 @@ end
 
 #### Using the get_project_time_series_with_http_info variant
 
-This returns an Array which contains the response data (`nil` in this case), status code and headers.
+This returns an Array which contains the response data, status code and headers.
 
-> <Array(nil, Integer, Hash)> get_project_time_series_with_http_info(organization_id, project_id, date_from, date_to, opts)
+> <Array(<ProjectRankTrackingTimeSeries>, Integer, Hash)> get_project_time_series_with_http_info(organization_id, project_id, date_from, date_to, opts)
 
 ```ruby
 begin
@@ -871,7 +879,7 @@ begin
   data, status_code, headers = api_instance.get_project_time_series_with_http_info(organization_id, project_id, date_from, date_to, opts)
   p status_code # => 2xx
   p headers # => { ... }
-  p data # => nil
+  p data # => <ProjectRankTrackingTimeSeries>
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_project_time_series_with_http_info: #{e}"
 end
@@ -889,12 +897,12 @@ end
 | **engines** | [**Array&lt;String&gt;**](String.md) | Repeatable, or comma-separated. | [optional] |
 | **countries** | [**Array&lt;String&gt;**](String.md) | ISO-3166 alpha-2 codes or English names. Must be configured on the project. | [optional] |
 | **query_cluster_ids** | [**Array&lt;String&gt;**](String.md) |  | [optional] |
-| **include_ungrouped_queries** | **Boolean** | 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. | [optional][default to false] |
+| **include_ungrouped_queries** | **Boolean** | 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. | [optional][default to false] |
 | **competitor_ids** | [**Array&lt;String&gt;**](String.md) | Repeatable, or comma-separated. Each id adds one series under the competitors map of every point. | [optional] |
 
 ### Return type
 
-nil (empty response body)
+[**ProjectRankTrackingTimeSeries**](ProjectRankTrackingTimeSeries.md)
 
 ### Authorization
 
@@ -903,12 +911,12 @@ nil (empty response body)
 ### HTTP request headers
 
 - **Content-Type**: Not defined
-- **Accept**: Not defined
+- **Accept**: application/json
 
 
 ## get_query_movers
 
-> get_query_movers(organization_id, project_id, date_from, date_to, opts)
+> <TrackedQueryMoversResponse> get_query_movers(organization_id, project_id, date_from, date_to, opts)
 
 Tracked queries ranked by how much a metric moved
 
@@ -941,7 +949,8 @@ opts = {
 
 begin
   # Tracked queries ranked by how much a metric moved
-  api_instance.get_query_movers(organization_id, project_id, date_from, date_to, opts)
+  result = api_instance.get_query_movers(organization_id, project_id, date_from, date_to, opts)
+  p result
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_query_movers: #{e}"
 end
@@ -949,9 +958,9 @@ end
 
 #### Using the get_query_movers_with_http_info variant
 
-This returns an Array which contains the response data (`nil` in this case), status code and headers.
+This returns an Array which contains the response data, status code and headers.
 
-> <Array(nil, Integer, Hash)> get_query_movers_with_http_info(organization_id, project_id, date_from, date_to, opts)
+> <Array(<TrackedQueryMoversResponse>, Integer, Hash)> get_query_movers_with_http_info(organization_id, project_id, date_from, date_to, opts)
 
 ```ruby
 begin
@@ -959,7 +968,7 @@ begin
   data, status_code, headers = api_instance.get_query_movers_with_http_info(organization_id, project_id, date_from, date_to, opts)
   p status_code # => 2xx
   p headers # => { ... }
-  p data # => nil
+  p data # => <TrackedQueryMoversResponse>
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_query_movers_with_http_info: #{e}"
 end
@@ -982,7 +991,7 @@ end
 
 ### Return type
 
-nil (empty response body)
+[**TrackedQueryMoversResponse**](TrackedQueryMoversResponse.md)
 
 ### Authorization
 
@@ -991,7 +1000,7 @@ nil (empty response body)
 ### HTTP request headers
 
 - **Content-Type**: Not defined
-- **Accept**: Not defined
+- **Accept**: application/json
 
 
 ## get_share_of_voice_formula
@@ -1000,7 +1009,7 @@ nil (empty response body)
 
 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.
 
 ### Examples
 
@@ -1067,11 +1076,11 @@ end
 
 ## get_tracked_query_time_series
 
-> get_tracked_query_time_series(organization_id, project_id, tracked_query_id, date_from, date_to, opts)
+> <TrackedQueryRankTrackingTimeSeries> get_tracked_query_time_series(organization_id, project_id, tracked_query_id, date_from, date_to, opts)
 
 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.
 
 ### Examples
 
@@ -1097,7 +1106,8 @@ opts = {
 
 begin
   # Rank-tracking time series of a single tracked query
-  api_instance.get_tracked_query_time_series(organization_id, project_id, tracked_query_id, date_from, date_to, opts)
+  result = api_instance.get_tracked_query_time_series(organization_id, project_id, tracked_query_id, date_from, date_to, opts)
+  p result
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_tracked_query_time_series: #{e}"
 end
@@ -1105,9 +1115,9 @@ end
 
 #### Using the get_tracked_query_time_series_with_http_info variant
 
-This returns an Array which contains the response data (`nil` in this case), status code and headers.
+This returns an Array which contains the response data, status code and headers.
 
-> <Array(nil, Integer, Hash)> get_tracked_query_time_series_with_http_info(organization_id, project_id, tracked_query_id, date_from, date_to, opts)
+> <Array(<TrackedQueryRankTrackingTimeSeries>, Integer, Hash)> get_tracked_query_time_series_with_http_info(organization_id, project_id, tracked_query_id, date_from, date_to, opts)
 
 ```ruby
 begin
@@ -1115,7 +1125,7 @@ begin
   data, status_code, headers = api_instance.get_tracked_query_time_series_with_http_info(organization_id, project_id, tracked_query_id, date_from, date_to, opts)
   p status_code # => 2xx
   p headers # => { ... }
-  p data # => nil
+  p data # => <TrackedQueryRankTrackingTimeSeries>
 rescue Mencoro::ApiError => e
   puts "Error when calling AnalyticsApi->get_tracked_query_time_series_with_http_info: #{e}"
 end
@@ -1135,7 +1145,7 @@ end
 
 ### Return type
 
-nil (empty response body)
+[**TrackedQueryRankTrackingTimeSeries**](TrackedQueryRankTrackingTimeSeries.md)
 
 ### Authorization
 
@@ -1144,7 +1154,7 @@ nil (empty response body)
 ### HTTP request headers
 
 - **Content-Type**: Not defined
-- **Accept**: Not defined
+- **Accept**: application/json
 
 
 ## get_tracking_coverage
@@ -1246,7 +1256,7 @@ opts = {
   engines: ['chatgpt'], # Array<String> | Repeatable, or comma-separated. Narrows which variants count towards each row.
   countries: ['inner_example'], # Array<String> | ISO-3166 alpha-2 codes or English names. Must be configured on the project.
   query_cluster_ids: ['inner_example'], # Array<String> | Restrict to keywords with a variant in these clusters. Each must belong to the project.
-  include_ungrouped_queries: true, # Boolean | Sent alone, restricts the listing to keywords whose variants belong to no cluster; sent with queryClusterIds, adds them to that selection.
+  include_ungrouped_queries: true, # Boolean | 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.
   status: 'active', # String | Restrict to variants with this status. A keyword whose variants disagree still reports statusSummary \"mixed\".
   check_frequencies: ['daily'], # Array<String> | Repeatable, or comma-separated.
   n_passes: [37], # Array<Integer> | Repeatable, or comma-separated. Restrict to variants configured with these pass counts.
@@ -1295,7 +1305,7 @@ end
 | **engines** | [**Array&lt;String&gt;**](String.md) | Repeatable, or comma-separated. Narrows which variants count towards each row. | [optional] |
 | **countries** | [**Array&lt;String&gt;**](String.md) | ISO-3166 alpha-2 codes or English names. Must be configured on the project. | [optional] |
 | **query_cluster_ids** | [**Array&lt;String&gt;**](String.md) | Restrict to keywords with a variant in these clusters. Each must belong to the project. | [optional] |
-| **include_ungrouped_queries** | **Boolean** | Sent alone, restricts the listing to keywords whose variants belong to no cluster; sent with queryClusterIds, adds them to that selection. | [optional][default to false] |
+| **include_ungrouped_queries** | **Boolean** | 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. | [optional][default to false] |
 | **status** | **String** | Restrict to variants with this status. A keyword whose variants disagree still reports statusSummary \&quot;mixed\&quot;. | [optional] |
 | **check_frequencies** | [**Array&lt;String&gt;**](String.md) | Repeatable, or comma-separated. | [optional] |
 | **n_passes** | [**Array&lt;Integer&gt;**](Integer.md) | Repeatable, or comma-separated. Restrict to variants configured with these pass counts. | [optional] |