Usage tools
- get_discovery_api_requests: Get API request usage statistics for an account over a date range.
- get_discovery_unique_visitors: Get monthly unique visitor counts for an account, with the contracted limit.
get_discovery_api_requests
Returns API request usage for an account, taken from the Setup > Usage > API Requests dashboard. It reports daily or monthly request_count values across the date range you request.
Use it to track quota consumption, watch traffic trends, spot anomalies by request type or environment, and audit usage across catalogs or sites. By default the report is organization-wide, so apply an account_name filter to narrow to one account. Usage is reported globally, so if you operate in more than one region, both are aggregated unless you filter to a region-specific account.
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
account_name | str | Yes | The account to query, for example 'your-account'. |
time_period_start | str | Yes | The start date in YYYY-MM-DD format, for example '2026-03-01'. |
time_period_end | str | Yes | The end date in YYYY-MM-DD format, for example '2026-04-30'. |
granularity | str | No | The time granularity, either 'daily' or 'monthly'. Defaults to 'daily'. |
filters | str | null | No | A filter in the format 'dimension:value'. Prefix with - to exclude, as in -environment:staging. |
The filters parameter accepts these dimensions:
| Dimension | Description | Example values |
|---|---|---|
environment | Production or staging. | production, staging |
status_code | HTTP status group. | 2xx, 4xx, 5xx |
request_type | The API request type. | keyword, suggest, category, bestseller, mlt, jfy, co-viewed, trending, thematic, visual-search |
catalog | The catalog name. | Your catalog name |
account_name | An account within the org. | An account name |
data_type | The type of data returned. | product, content |
region | The geographic region. | us, eu |
site | A specific site. | A domain key |
Response parameters
The tool returns a DiscoveryUsageResponse object with the following parameters:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
organization | str | null | The parent organization resolved from account_name. |
data | any | null | The usage payload as freeform JSON. |
error | str | null | Error message if the request failed. |
The data.body payload includes these key fields:
| Field | Description |
|---|---|
results | Time-period results, each with time_period_start, time_period_end, total, and groups. |
results[].total.request_count.value | The total request count for the period. |
results[].groups | The per-group breakdown when a group-by is applied. |
group_definitions | The names of the groups in the response. |
get_discovery_unique_visitors
Returns monthly unique visitor (MUV) counts for an account, taken from the Setup > Usage > Unique Visitors dashboard. It reports actual MUV per month and, for customers on MUV-based pricing plans, the contracted MUV limit.
Use it to track contract compliance, watch year-over-year visitor trends, and forecast usage against your contracted limit. MUVs are counted from unique cookie IDs captured by the tracking pixel, so missing or static cookie IDs can cause discrepancies against other tools. The dashboard keeps up to 24 months of history, and each month's data is available from the 2nd of the following month.
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
account_name | str | Yes | The account to query, for example 'your-account'. |
time_period_start | str | Yes | The start month in YYYY-MM format, for example '2024-04'. |
time_period_end | str | Yes | The end month in YYYY-MM format, for example '2026-03'. |
include_contracted | bool | No | Include the contracted_muv limit alongside actual muv. Meaningful only for MUV-based plans. Defaults to true. |
Response parameters
The tool returns a DiscoveryUsageResponse object with the following parameters:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
organization | str | null | The parent organization resolved from account_name. |
data | any | null | The usage payload as freeform JSON. |
error | str | null | Error message if the request failed. |
The data.body payload includes these key fields:
| Field | Description |
|---|---|
results | Monthly results, each with time_period_start, time_period_end, total, and groups. |
results[].total.muv.value | The monthly unique visitor count. |
results[].total.contracted_muv.value | The contracted MUV limit, when include_contracted is true and the plan applies. |