mencoro 1.0.1 → 2.0.1

data/docs/ProjectsApi.md

@@ -9,6 +9,7 @@ All URIs are relative to *https://api.mencoro.com*
 | [**create_project**](ProjectsApi.md#create_project) | **POST** /api/v1/organizations/{organizationId}/projects | Create a project and the brand monitoring profile its checks run against |
 | [**delete_competitor**](ProjectsApi.md#delete_competitor) | **DELETE** /api/v1/organizations/{organizationId}/projects/{projectId}/competitors/{competitorId} | Remove a competitor from a project |
 | [**get_brand_profile**](ProjectsApi.md#get_brand_profile) | **GET** /api/v1/organizations/{organizationId}/projects/{projectId}/brand-profile | Get a project's brand monitoring profile |
+| [**get_competitor**](ProjectsApi.md#get_competitor) | **GET** /api/v1/organizations/{organizationId}/projects/{projectId}/competitors/{competitorId} | Get one of a project's competitors |
 | [**get_project**](ProjectsApi.md#get_project) | **GET** /api/v1/organizations/{organizationId}/projects/{projectId} | Get a project and its brand monitoring configuration |
 | [**list_competitors**](ProjectsApi.md#list_competitors) | **GET** /api/v1/organizations/{organizationId}/projects/{projectId}/competitors | List the competitors tracked by a project |
 | [**list_projects**](ProjectsApi.md#list_projects) | **GET** /api/v1/organizations/{organizationId}/projects | List an organization's projects |
@@ -173,7 +174,7 @@ end
 
 Create a project and the brand monitoring profile its checks run against
 
-Minimum role: manager, in an active organization. Requires the \"write\" capability. Creates the project, the brand monitoring profile holding the domains and brand names to watch, and one competitor per entry of `competitors`, in a single call. The project id is minted by the server; a caller-supplied id is rejected as an unknown field. What is NOT done: no tracked queries are created, no check is run and no scraping is scheduled — a new project has nothing collected against it until tracked queries are added. Each website entry may be a full URL or a bare domain: a URL is reduced to its host with any leading \"www.\" removed, so \"https://www.acme.com/pricing\" is stored as \"acme.com\". Duplicate domains and duplicate brand names are collapsed, exactly as the stored value objects do. Send an Idempotency-Key: a retry with the same key and the same body returns this same project instead of creating a second one.
+Minimum role: manager, in an active organization, with access to every project of it: a member restricted to selected projects is refused as a role below the minimum is. Requires the \"write\" capability. Creates the project, the brand monitoring profile holding the domains and brand names to watch, and one competitor per entry of `competitors`, in a single call. The project id is minted by the server; a caller-supplied id is rejected as an unknown field. What is NOT done: no tracked queries are created, no check is run and no scraping is scheduled — a new project has nothing collected against it until tracked queries are added. Each website entry may be a full URL or a bare domain: a URL is reduced to its host with any leading \"www.\" removed, so \"https://www.acme.com/pricing\" is stored as \"acme.com\". Duplicate domains and duplicate brand names are collapsed, exactly as the stored value objects do. Send an Idempotency-Key: a retry with the same key and the same body returns this same project instead of creating a second one.
 
 ### Examples
 
@@ -386,6 +387,79 @@ end
 - **Accept**: application/json
 
 
+## get_competitor
+
+> <CompetitorResource> get_competitor(organization_id, project_id, competitor_id)
+
+Get one of a project's competitors
+
+Minimum role: viewer. Returns a single competitor of the project, the same projection the competitor listing returns for each of its rows. A competitor belonging to another project answers 404, the same answer an unknown id and a malformed one get, so the API never confirms that a competitor the caller cannot reach exists. A project whose brand monitoring profile has not been created yet has no competitors at all and answers 404 for any competitor id.
+
+### Examples
+
+```ruby
+require 'time'
+require 'mencoro'
+# setup authorization
+Mencoro.configure do |config|
+  # Configure Bearer authorization: ApiKey
+  config.access_token = 'YOUR_BEARER_TOKEN'
+end
+
+api_instance = Mencoro::ProjectsApi.new
+organization_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | 
+project_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | Must belong to the organization in the path.
+competitor_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | Must belong to the project in the path.
+
+begin
+  # Get one of a project's competitors
+  result = api_instance.get_competitor(organization_id, project_id, competitor_id)
+  p result
+rescue Mencoro::ApiError => e
+  puts "Error when calling ProjectsApi->get_competitor: #{e}"
+end
+```
+
+#### Using the get_competitor_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<CompetitorResource>, Integer, Hash)> get_competitor_with_http_info(organization_id, project_id, competitor_id)
+
+```ruby
+begin
+  # Get one of a project's competitors
+  data, status_code, headers = api_instance.get_competitor_with_http_info(organization_id, project_id, competitor_id)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <CompetitorResource>
+rescue Mencoro::ApiError => e
+  puts "Error when calling ProjectsApi->get_competitor_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **organization_id** | **String** |  |  |
+| **project_id** | **String** | Must belong to the organization in the path. |  |
+| **competitor_id** | **String** | Must belong to the project in the path. |  |
+
+### Return type
+
+[**CompetitorResource**](CompetitorResource.md)
+
+### Authorization
+
+[ApiKey](../README.md#ApiKey)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json
+
+
 ## get_project
 
 > <ProjectDetailResource> get_project(organization_id, project_id)
@@ -542,7 +616,7 @@ end
 
 List an organization's projects
 
-Minimum role: viewer. Metrics come from the same read model the application uses, so the figures match what the product shows. A null metric means \"not known yet\", never zero.Send `Accept: text/csv` to receive the same page as a CSV download instead of JSON: same filters, same authorization, same page window and the same maximum of 100 rows — it is this page in another format, not a bulk export, so a whole collection is still read by paging. The CSV carries no `total`, because a table whose every row is a record has nowhere to put one; read it from the JSON representation of the same request. A list-valued field is joined into one cell with `; ` as a display projection — parse the JSON if you need the structure. Cells beginning with `=`, `+`, `-` or `@` are prefixed with an apostrophe so a spreadsheet treats them as text rather than running them as formulas.
+Minimum role: viewer. Metrics come from the same read model the application uses, so the figures match what the product shows. A null metric means \"not known yet\", never zero. For a member restricted to selected projects, the list and `total` cover those projects only. Send `Accept: text/csv` to receive the same page as a CSV download instead of JSON: same filters, same authorization, same page window and the same maximum of 100 rows — it is this page in another format, not a bulk export, so a whole collection is still read by paging. The CSV carries no `total`, because a table whose every row is a record has nowhere to put one; read it from the JSON representation of the same request. A list-valued field is joined into one cell with `; ` as a display projection — parse the JSON if you need the structure. Cells beginning with `=`, `+`, `-` or `@` are prefixed with an apostrophe so a spreadsheet treats them as text rather than running them as formulas.
 
 ### Examples
 

data/docs/SearchTrackedQueryMentionMatches200Response.md

@@ -0,0 +1,20 @@
+# Mencoro::SearchTrackedQueryMentionMatches200Response
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **items** | [**Array<MentionMatchResource>**](MentionMatchResource.md) |  | [optional] |
+| **total** | **Integer** |  | [optional] |
+
+## Example
+
+```ruby
+require 'mencoro'
+
+instance = Mencoro::SearchTrackedQueryMentionMatches200Response.new(
+  items: null,
+  total: null
+)
+```
+

data/docs/SearchTrackedQuerySerpMatches200Response.md

@@ -0,0 +1,20 @@
+# Mencoro::SearchTrackedQuerySerpMatches200Response
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **items** | [**Array<SerpMatchResource>**](SerpMatchResource.md) |  | [optional] |
+| **total** | **Integer** |  | [optional] |
+
+## Example
+
+```ruby
+require 'mencoro'
+
+instance = Mencoro::SearchTrackedQuerySerpMatches200Response.new(
+  items: null,
+  total: null
+)
+```
+

data/docs/SerpMatchResource.md

@@ -0,0 +1,30 @@
+# Mencoro::SerpMatchResource
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **tracked_query_id** | **String** |  |  |
+| **project_id** | **String** |  |  |
+| **engine** | **String** |  |  |
+| **search_page_id** | **String** |  |  |
+| **competitor_id** | **String** |  | [optional] |
+| **position** | **Integer** |  |  |
+| **detected_at** | **Time** |  |  |
+
+## Example
+
+```ruby
+require 'mencoro'
+
+instance = Mencoro::SerpMatchResource.new(
+  tracked_query_id: null,
+  project_id: null,
+  engine: null,
+  search_page_id: null,
+  competitor_id: null,
+  position: null,
+  detected_at: null
+)
+```
+

data/docs/SetMemberProjectAccessRequest.md

@@ -0,0 +1,20 @@
+# Mencoro::SetMemberProjectAccessRequest
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **mode** | **String** |  |  |
+| **project_ids** | **Array<String>** | The projects of the organization a selected access reaches: at least one and at most 500. Omit it, or send an empty list, for all. | [optional] |
+
+## Example
+
+```ruby
+require 'mencoro'
+
+instance = Mencoro::SetMemberProjectAccessRequest.new(
+  mode: null,
+  project_ids: null
+)
+```
+

data/docs/SubscriptionResource.md

@@ -15,7 +15,7 @@
 | **cancelled_at** | **Time** | When the subscription was terminally cancelled. Null while it has not been. | [optional] |
 | **scheduled_to_cancel_at** | **Time** | When a scheduled cancellation takes effect, while the subscription is still running. Null when none is scheduled. | [optional] |
 | **grace_period_ends_at** | **Time** | When paid access ends after a cancellation. Null when the subscription is not cancelled. | [optional] |
-| **deactivation_reason** | **String** | Why the subscription is currently inactive. Null for an active subscription, and meaningless once \"cancelledAt\" is set - the cancellation supersedes it. | [optional] |
+| **deactivation_reason** | **String** | Why the subscription is currently inactive. Null for an active subscription and for a member restricted to selected projects, and meaningless once \"cancelledAt\" is set - the cancellation supersedes it. | [optional] |
 | **is_entitled** | **Boolean** | Whether the organization may use paid features right now: active, or cancelled but still inside its paid grace window. |  |
 
 ## Example

data/docs/TimeSeriesPoint.md

@@ -0,0 +1,22 @@
+# Mencoro::TimeSeriesPoint
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **raw_date** | **String** |  |  |
+| **brand** | [**PerEntityMetrics**](PerEntityMetrics.md) |  |  |
+| **competitors** | [**Hash<String, PerEntityMetrics>**](PerEntityMetrics.md) |  |  |
+
+## Example
+
+```ruby
+require 'mencoro'
+
+instance = Mencoro::TimeSeriesPoint.new(
+  raw_date: null,
+  brand: null,
+  competitors: null
+)
+```
+

data/docs/TrackedQueriesApi.md

@@ -24,6 +24,8 @@ All URIs are relative to *https://api.mencoro.com*
 | [**report_ai_response**](TrackedQueriesApi.md#report_ai_response) | **POST** /api/v1/organizations/{organizationId}/projects/{projectId}/tracked-queries/{trackedQueryId}/responses/{aiResponseId}/report | Report a problem with a captured AI answer |
 | [**resume_tracked_query**](TrackedQueriesApi.md#resume_tracked_query) | **PUT** /api/v1/organizations/{organizationId}/projects/{projectId}/tracked-queries/{trackedQueryId}/resume | Resume a tracked query |
 | [**search_tracked_queries**](TrackedQueriesApi.md#search_tracked_queries) | **GET** /api/v1/organizations/{organizationId}/projects/{projectId}/tracked-queries | Search a project's tracked queries |
+| [**search_tracked_query_mention_matches**](TrackedQueriesApi.md#search_tracked_query_mention_matches) | **GET** /api/v1/organizations/{organizationId}/projects/{projectId}/tracked-queries/{trackedQueryId}/mention-matches | List stored mention matches of a tracked query |
+| [**search_tracked_query_serp_matches**](TrackedQueriesApi.md#search_tracked_query_serp_matches) | **GET** /api/v1/organizations/{organizationId}/projects/{projectId}/tracked-queries/{trackedQueryId}/serp-matches | List stored serp matches of a tracked query |
 
 
 ## add_clusters_to_tracked_query
@@ -334,7 +336,7 @@ end
 
 Check several tracked queries now
 
-Minimum role: manager. Asks for a fresh check of up to 100 named tracked queries straight away, ignoring how recently each was last checked. Answers 200 with per-item results and NO job id: a check that is already in flight for a query is reused rather than started again, so there is no id this operation could hand back that is guaranteed to exist. Follow progress on the tracked query itself — its lastCheckedAt advances when the check completes. A successful item means the check was accepted for submission with budget available for it at that moment; it does not mean the check has run. A checked query costs one budget unit per pass (nPasses), and items that do not fit the remaining budget are reported as failed with `check_budget_forecast_exhausted`, or `subscription_not_found` when the organization has no entitled subscription — they are never reported as successful. That budget figure is a forecast for this batch, and a pessimistic one: a tracked query already being checked is joined to the check in flight and costs nothing, but it is still debited here, so an item refused this way may have fitted. Resubmit it in a later batch rather than treating the refusal as a statement about your subscription. A paused query is reported as failed with `tracked_query_already_paused`: paused queries are never checked. An id that is not a tracked query of this project is reported as failed with `tracked_query_not_found`, exactly as an id that does not exist. Requires an Idempotency-Key header; a retry must repeat the same ids in the same order.
+Minimum role: manager. Asks for a fresh check of up to 100 named tracked queries straight away, ignoring how recently each was last checked. Answers 200 with per-item results and NO job id: a check that is already in flight for a query is reused rather than started again, so there is no id this operation could hand back that is guaranteed to exist. Follow progress on the tracked query itself — its lastCheckedAt advances when the check completes. A successful item means the check was accepted for submission with budget available for it at that moment; it does not mean the check has run. A checked query costs one check per pass; a Claude pass counts as five (nPasses), and items that do not fit the remaining budget are reported as failed with `check_budget_forecast_exhausted`, or `subscription_not_found` when the organization has no entitled subscription — they are never reported as successful. That budget figure is a forecast for this batch, and a pessimistic one: a tracked query already being checked is joined to the check in flight and costs nothing, but it is still debited here, so an item refused this way may have fitted. Resubmit it in a later batch rather than treating the refusal as a statement about your subscription. A paused query is reported as failed with `tracked_query_already_paused`: paused queries are never checked. An id that is not a tracked query of this project is reported as failed with `tracked_query_not_found`, exactly as an id that does not exist. Requires an Idempotency-Key header; a retry must repeat the same ids in the same order.
 
 ### Examples
 
@@ -938,7 +940,7 @@ end
 
 Count a project's tracked queries and price checking them
 
-Minimum role: viewer. Two numbers about one project: how many tracked queries it holds, and what force-checking that same set would cost. Omit `status` to count every tracked query whatever its status; send `active` or `paused` to count and price only those. `checkCost` is a PRICED DRY RUN expressed in check budget units — one unit per pass, the same unit the plan allowance is counted in, so it is directly comparable with `checksAvailable` from the entitlements operation — and it is the sum of each matched tracked query's configured passes. Asking reserves nothing, debits nothing and starts no check. It is deliberately NOT a forecast of what the check-all operation will consume: that operation skips paused queries, skips a query whose check is already pending or running, re-runs a check awaiting retry without charging for it again, and stops at whatever budget is left — none of which is subtracted here. Count with `status=active` for the figure closest to a full check-all. Both numbers are read from the write model, so a tracked query created moments ago is already in them; that is why they can be AHEAD of the `total` returned by the tracked-queries listing, which counts a search projection, and ahead of the keyword listings, which read projections refreshed in the background. Summing the unfiltered count over every project of an organization, archived projects included, reproduces countOrganizationTrackedQueries, which counts through the same counter in the same store. An archived project still answers, because this is a read, but no check can be submitted there while it stays archived, so its cost is hypothetical. For a month of scheduled rounds across the whole organization instead of one round over one project, read getOrganizationProjectedMonthlyChecks. No monetary amount is published or implied: the cost of a check is published only in budget units.
+Minimum role: viewer. Two numbers about one project: how many tracked queries it holds, and what force-checking that same set would cost. Omit `status` to count every tracked query whatever its status; send `active` or `paused` to count and price only those. `checkCost` is a PRICED DRY RUN expressed in checks — five checks per Claude pass and one check per pass for every other engine, the same currency as the plan allowance, so it is directly comparable with `checksAvailable` from the entitlements operation — and it is the sum of each matched tracked query's configured passes multiplied by its engine weight. Asking reserves nothing, debits nothing and starts no check. It is deliberately NOT a forecast of what the check-all operation will consume: that operation skips paused queries, skips a query whose check is already pending or running, re-runs a check awaiting retry without charging for it again, and stops at whatever budget is left — none of which is subtracted here. Count with `status=active` for the figure closest to a full check-all. Both numbers are read from the write model, so a tracked query created moments ago is already in them; that is why they can be AHEAD of the `total` returned by the tracked-queries listing, which counts a search projection, and ahead of the keyword listings, which read projections refreshed in the background. Summing the unfiltered count over every project of an organization, archived projects included, reproduces countOrganizationTrackedQueries, which counts through the same counter in the same store. An archived project still answers, because this is a read, but no check can be submitted there while it stays archived, so its cost is hypothetical. For a month of scheduled rounds across the whole organization instead of one round over one project, read getOrganizationProjectedMonthlyChecks. No monetary amount is published or implied: the cost of a check is published only in checks.
 
 ### Examples
 
@@ -1013,7 +1015,7 @@ end
 
 Check every eligible tracked query of a project now
 
-Minimum role: manager. Submits a fresh check for every eligible tracked query of the project, ignoring how recently each was last checked, least-recently-checked first, and at most 1000 tracked queries per call. Eligible is narrower than active: a paused query is skipped, and so is one whose check is already pending or running for the same engine. A query whose check is awaiting a retry is included and, WHEN THE ENGINE HAS NOT CHANGED SINCE, costs nothing extra, because its first submission already paid for it; if the engine did change, the pending run is replaced and the replacement is paid for. What is left is trimmed to what the organization's remaining check budget can pay for — a check costs one budget unit per pass. While a subscription is cancelled but still inside its paid grace window nothing is submitted at all and `submitted` is 0; name the queries explicitly through the check operation to run them in that window. CALLING AGAIN DOES NOT CONTINUE WHERE THIS CALL STOPPED: submissions are handed to a worker, and a tracked query stops being selected only once that worker has started its check, so a second call made before the queue drains selects and submits the same tracked queries again. That is safe while the first check is still running — the duplicate is collapsed, and nothing is checked or charged twice — but a check that has already finished is run again and charged again, because this operation ignores staleness by design. To cover a project with more than 1000 eligible tracked queries, wait for the submitted wave to be picked up — each tracked query's lastCheckedAt advances when its check completes — and call again then. The response lists the tracked queries submitted and carries NO job id: a check already in flight is reused rather than started again, so no id could be guaranteed to exist. Submission is accepted, not completed: a listed tracked query can still lose the last budget units to another caller before the worker reaches it. The request takes no body, and any field sent is rejected. Requires an Idempotency-Key header.
+Minimum role: manager. Submits a fresh check for every eligible tracked query of the project, ignoring how recently each was last checked, least-recently-checked first, and at most 1000 tracked queries per call. Eligible is narrower than active: a paused query is skipped, and so is one whose check is already pending or running for the same engine. A query whose check is awaiting a retry is included and, WHEN THE ENGINE HAS NOT CHANGED SINCE, costs nothing extra, because its first submission already paid for it; if the engine did change, the pending run is replaced and the replacement is paid for. What is left is trimmed to what the organization's remaining check budget can pay for — a check costs one check per pass; a Claude pass counts as five. A subscription that is cancelled but still inside its paid grace window keeps paying for checks until that window ends. CALLING AGAIN DOES NOT CONTINUE WHERE THIS CALL STOPPED: submissions are handed to a worker, and a tracked query stops being selected only once that worker has started its check, so a second call made before the queue drains selects and submits the same tracked queries again. That is safe while the first check is still running — the duplicate is collapsed, and nothing is checked or charged twice — but a check that has already finished is run again and charged again, because this operation ignores staleness by design. To cover a project with more than 1000 eligible tracked queries, wait for the submitted wave to be picked up — each tracked query's lastCheckedAt advances when its check completes — and call again then. The response lists the tracked queries submitted and carries NO job id: a check already in flight is reused rather than started again, so no id could be guaranteed to exist. Submission is accepted, not completed: a listed tracked query can still lose the last budget units to another caller before the worker reaches it. The request takes no body, and any field sent is rejected. Requires an Idempotency-Key header.
 
 ### Examples
 
@@ -1547,3 +1549,173 @@ end
 - **Content-Type**: Not defined
 - **Accept**: application/json, text/csv
 
+
+## search_tracked_query_mention_matches
+
+> <SearchTrackedQueryMentionMatches200Response> search_tracked_query_mention_matches(organization_id, project_id, tracked_query_id, opts)
+
+List stored mention matches of a tracked query
+
+Minimum role: viewer. Text mentions across own brand and tracked or untracked competitors. Citation-only rows are excluded before pagination. Read mentionRelation to distinguish own brand from untracked competitors; a null competitorId alone does not classify the mention. Newest first by detection time, with an id tie-break. Dates cover whole UTC days. Only the retained 16-month window is readable, including when dateFrom is omitted. Unknown filters are rejected. The total counts all matching rows before pagination. Send Accept: text/csv for the same bounded page and filters as CSV, with formula-safe cells and no total.
+
+### Examples
+
+```ruby
+require 'time'
+require 'mencoro'
+# setup authorization
+Mencoro.configure do |config|
+  # Configure Bearer authorization: ApiKey
+  config.access_token = 'YOUR_BEARER_TOKEN'
+end
+
+api_instance = Mencoro::TrackedQueriesApi.new
+organization_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | 
+project_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | 
+tracked_query_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | 
+opts = {
+  date_from: Date.parse('2013-10-20'), # Date | Inclusive UTC day; defaults to the retention floor.
+  date_to: Date.parse('2013-10-20'), # Date | Inclusive UTC day.
+  limit: 56, # Integer | 
+  offset: 56, # Integer | 
+  sort_order: 'asc' # String | 
+}
+
+begin
+  # List stored mention matches of a tracked query
+  result = api_instance.search_tracked_query_mention_matches(organization_id, project_id, tracked_query_id, opts)
+  p result
+rescue Mencoro::ApiError => e
+  puts "Error when calling TrackedQueriesApi->search_tracked_query_mention_matches: #{e}"
+end
+```
+
+#### Using the search_tracked_query_mention_matches_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<SearchTrackedQueryMentionMatches200Response>, Integer, Hash)> search_tracked_query_mention_matches_with_http_info(organization_id, project_id, tracked_query_id, opts)
+
+```ruby
+begin
+  # List stored mention matches of a tracked query
+  data, status_code, headers = api_instance.search_tracked_query_mention_matches_with_http_info(organization_id, project_id, tracked_query_id, opts)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <SearchTrackedQueryMentionMatches200Response>
+rescue Mencoro::ApiError => e
+  puts "Error when calling TrackedQueriesApi->search_tracked_query_mention_matches_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **organization_id** | **String** |  |  |
+| **project_id** | **String** |  |  |
+| **tracked_query_id** | **String** |  |  |
+| **date_from** | **Date** | Inclusive UTC day; defaults to the retention floor. | [optional] |
+| **date_to** | **Date** | Inclusive UTC day. | [optional] |
+| **limit** | **Integer** |  | [optional][default to 20] |
+| **offset** | **Integer** |  | [optional][default to 0] |
+| **sort_order** | **String** |  | [optional][default to &#39;desc&#39;] |
+
+### Return type
+
+[**SearchTrackedQueryMentionMatches200Response**](SearchTrackedQueryMentionMatches200Response.md)
+
+### Authorization
+
+[ApiKey](../README.md#ApiKey)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json, text/csv
+
+
+## search_tracked_query_serp_matches
+
+> <SearchTrackedQuerySerpMatches200Response> search_tracked_query_serp_matches(organization_id, project_id, tracked_query_id, opts)
+
+List stored serp matches of a tracked query
+
+Minimum role: viewer. Stored organic-search matches with the competitor attribution and position recorded at detection time. A null competitorId identifies the own-brand match. These are historical matches, not a reclassification using the current brand profile. Newest first by detection time, with an id tie-break. Dates cover whole UTC days. Only the retained 16-month window is readable, including when dateFrom is omitted. Unknown filters are rejected. The total counts all matching rows before pagination. Send Accept: text/csv for the same bounded page and filters as CSV, with formula-safe cells and no total.
+
+### Examples
+
+```ruby
+require 'time'
+require 'mencoro'
+# setup authorization
+Mencoro.configure do |config|
+  # Configure Bearer authorization: ApiKey
+  config.access_token = 'YOUR_BEARER_TOKEN'
+end
+
+api_instance = Mencoro::TrackedQueriesApi.new
+organization_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | 
+project_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | 
+tracked_query_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | 
+opts = {
+  date_from: Date.parse('2013-10-20'), # Date | Inclusive UTC day; defaults to the retention floor.
+  date_to: Date.parse('2013-10-20'), # Date | Inclusive UTC day.
+  limit: 56, # Integer | 
+  offset: 56, # Integer | 
+  sort_order: 'asc' # String | 
+}
+
+begin
+  # List stored serp matches of a tracked query
+  result = api_instance.search_tracked_query_serp_matches(organization_id, project_id, tracked_query_id, opts)
+  p result
+rescue Mencoro::ApiError => e
+  puts "Error when calling TrackedQueriesApi->search_tracked_query_serp_matches: #{e}"
+end
+```
+
+#### Using the search_tracked_query_serp_matches_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<SearchTrackedQuerySerpMatches200Response>, Integer, Hash)> search_tracked_query_serp_matches_with_http_info(organization_id, project_id, tracked_query_id, opts)
+
+```ruby
+begin
+  # List stored serp matches of a tracked query
+  data, status_code, headers = api_instance.search_tracked_query_serp_matches_with_http_info(organization_id, project_id, tracked_query_id, opts)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <SearchTrackedQuerySerpMatches200Response>
+rescue Mencoro::ApiError => e
+  puts "Error when calling TrackedQueriesApi->search_tracked_query_serp_matches_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **organization_id** | **String** |  |  |
+| **project_id** | **String** |  |  |
+| **tracked_query_id** | **String** |  |  |
+| **date_from** | **Date** | Inclusive UTC day; defaults to the retention floor. | [optional] |
+| **date_to** | **Date** | Inclusive UTC day. | [optional] |
+| **limit** | **Integer** |  | [optional][default to 20] |
+| **offset** | **Integer** |  | [optional][default to 0] |
+| **sort_order** | **String** |  | [optional][default to &#39;desc&#39;] |
+
+### Return type
+
+[**SearchTrackedQuerySerpMatches200Response**](SearchTrackedQuerySerpMatches200Response.md)
+
+### Authorization
+
+[ApiKey](../README.md#ApiKey)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json, text/csv
+

data/docs/TrackedQueryCountResource.md

@@ -5,7 +5,7 @@
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
 | **count** | **Integer** | Tracked queries in the project matching the status filter. Every status when none was sent. |  |
-| **check_cost** | **Integer** | Budget cost of force-checking exactly those tracked queries, in check budget units: the sum of each one's configured passes. One unit per pass, the same unit the plan allowance is counted in. Reserves nothing and debits nothing. |  |
+| **check_cost** | **Integer** | Budget cost of force-checking exactly those tracked queries, in checks: the sum of each one's configured passes multiplied by its engine weight. Five checks per Claude pass and one check per pass for every other engine, the same currency as the plan allowance. Reserves nothing and debits nothing. |  |
 
 ## Example
 

data/docs/TrackedQueryMoverRow.md

@@ -0,0 +1,58 @@
+# Mencoro::TrackedQueryMoverRow
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **tracked_query_id** | **String** |  |  |
+| **query_text** | **String** |  |  |
+| **engine** | **String** |  |  |
+| **country** | **String** |  |  |
+| **avg_serp_position** | **Float** |  | [optional] |
+| **trend_serp** | **Float** |  | [optional] |
+| **avg_shopping_position** | **Float** |  | [optional] |
+| **trend_shopping** | **Float** |  | [optional] |
+| **avg_mention_position** | **Float** |  | [optional] |
+| **trend_mention** | **Float** |  | [optional] |
+| **avg_link_position** | **Float** |  | [optional] |
+| **trend_link** | **Float** |  | [optional] |
+| **share_of_voice** | **Float** |  | [optional] |
+| **trend_share_of_voice** | **Float** |  | [optional] |
+| **positivity_index** | **Integer** |  | [optional] |
+| **trend_positivity** | **Integer** |  | [optional] |
+| **sentiment_positive** | **Integer** |  |  |
+| **sentiment_neutral** | **Integer** |  |  |
+| **sentiment_negative** | **Integer** |  |  |
+| **mention_count** | **Integer** |  |  |
+| **mention_type_counts** | [**MentionTypeCounts**](MentionTypeCounts.md) |  |  |
+
+## Example
+
+```ruby
+require 'mencoro'
+
+instance = Mencoro::TrackedQueryMoverRow.new(
+  tracked_query_id: null,
+  query_text: null,
+  engine: null,
+  country: null,
+  avg_serp_position: null,
+  trend_serp: null,
+  avg_shopping_position: null,
+  trend_shopping: null,
+  avg_mention_position: null,
+  trend_mention: null,
+  avg_link_position: null,
+  trend_link: null,
+  share_of_voice: null,
+  trend_share_of_voice: null,
+  positivity_index: null,
+  trend_positivity: null,
+  sentiment_positive: null,
+  sentiment_neutral: null,
+  sentiment_negative: null,
+  mention_count: null,
+  mention_type_counts: null
+)
+```
+

data/docs/TrackedQueryMoversResponse.md

@@ -0,0 +1,22 @@
+# Mencoro::TrackedQueryMoversResponse
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **rows** | [**Array<TrackedQueryMoverRow>**](TrackedQueryMoverRow.md) |  |  |
+| **total** | **Integer** |  |  |
+| **data_dirty_since** | **String** |  | [optional] |
+
+## Example
+
+```ruby
+require 'mencoro'
+
+instance = Mencoro::TrackedQueryMoversResponse.new(
+  rows: null,
+  total: null,
+  data_dirty_since: null
+)
+```
+

data/docs/TrackedQueryRankTrackingTimeSeries.md

@@ -0,0 +1,20 @@
+# Mencoro::TrackedQueryRankTrackingTimeSeries
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **points** | [**Array<TimeSeriesPoint>**](TimeSeriesPoint.md) |  |  |
+| **data_dirty_since** | **String** |  | [optional] |
+
+## Example
+
+```ruby
+require 'mencoro'
+
+instance = Mencoro::TrackedQueryRankTrackingTimeSeries.new(
+  points: null,
+  data_dirty_since: null
+)
+```
+

data/docs/TrackedQueryUsageResource.md

@@ -4,7 +4,7 @@
 
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
-| **tracked_query_count** | **Integer** | Tracked queries across every project of the organization, archived projects included, counting active and paused queries alike. Never null; 0 means none are configured. |  |
+| **tracked_query_count** | **Integer** | Tracked queries across every project of the organization the caller can access, archived projects included, counting active and paused queries alike. Never null; 0 means none are configured. |  |
 
 ## Example
 

data/lib/mencoro/api/account_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
@@ -77,7 +77,7 @@ module Mencoro
     end
 
     # Counts across everything the key can reach
-    # Aggregate counts over every organization the key's owner is an active member of, narrowed to the key's scope — the same set /api/v1/organizations pages through. `organizations.total` is that set's size; `projects.total` and `projects.active` count the projects inside it, archived ones included in the total and excluded from the active figure. Every value is an exact count: zero means zero, and no value here is ever null or unknown. Per-organization billing and usage figures are not part of this response; read them from the subscription and entitlements operations instead.
+    # Aggregate counts over every organization the key's owner is an active member of, narrowed to the key's scope — the same set /api/v1/organizations pages through. `organizations.total` is that set's size; `projects.total` and `projects.active` count the projects inside it the owner can access, archived ones included in the total and excluded from the active figure. Every value is an exact count: zero means zero, and no value here is ever null or unknown. Per-organization billing and usage figures are not part of this response; read them from the subscription and entitlements operations instead.
     # @param [Hash] opts the optional parameters
     # @return [GetMeStats200Response]
     def get_me_stats(opts = {})
@@ -86,7 +86,7 @@ module Mencoro
     end
 
     # Counts across everything the key can reach
-    # Aggregate counts over every organization the key's owner is an active member of, narrowed to the key's scope — the same set /api/v1/organizations pages through. `organizations.total` is that set's size; `projects.total` and `projects.active` count the projects inside it, archived ones included in the total and excluded from the active figure. Every value is an exact count: zero means zero, and no value here is ever null or unknown. Per-organization billing and usage figures are not part of this response; read them from the subscription and entitlements operations instead.
+    # Aggregate counts over every organization the key's owner is an active member of, narrowed to the key's scope — the same set /api/v1/organizations pages through. `organizations.total` is that set's size; `projects.total` and `projects.active` count the projects inside it the owner can access, archived ones included in the total and excluded from the active figure. Every value is an exact count: zero means zero, and no value here is ever null or unknown. Per-organization billing and usage figures are not part of this response; read them from the subscription and entitlements operations instead.
     # @param [Hash] opts the optional parameters
     # @return [Array<(GetMeStats200Response, Integer, Hash)>] GetMeStats200Response data, response status code and response headers
     def get_me_stats_with_http_info(opts = {})