Skip to main content
Glama

APIClaw

by io.apiclaw.api
OverviewDiscussionsAdmin

openapi_v2_voc_trend

Get the review and demand-tag trend

  1. Function

Return how reviews and demand tags change over time for one ASIN set or one category: one point per week (Monday to Sunday, UTC) or month, each with reviewCount, average rating, rating distribution, sentiment counts and rates, and the count and share of the window's top tags per dimension (default painPoints, scenarios, buyingFactors; topN 1-30, default 10). Same scope and merge rules as /voc/analysis: ASIN mode covers every review of the parents the ASINs belong to (several ASINs of one parent count once; context.resolvedAsins lists the ASINs that took part), and the points' reviewCount sums to /voc/analysis reviewCount for the same window. Tags are chosen by their count over the whole window, so every point reports the same tag set and a missing tag shows count 0. Every period of the window has a point; a period without reviews has reviewCount 0 and null metrics. reviewCount is the number of reviews that were tagged and entered the statistics, not total review volume, and coverage rises year over year — do not read a rising reviewCount as growing review volume. avgRating is computed from tagged reviews only and runs about 0.01 star below the average over all reviews, so a period-to-period change of that size is not a real change; whether sentiment and tag shares carry a similar bias has not been verified. Samples are sparse: most single parents have fewer than 5 tagged reviews in a week or month, so points below lowSampleThreshold carry lowSample=true and context.lowSamplePeriodCount counts them. Window: dateFrom+dateTo, or period (default 6m, resolved like /voc/analysis), widened to whole periods; at most 25 months or 52 weeks, so weekly granularity takes period up to 6m (1y and 2y are rejected with period_limit_exceeded — give explicit dates or use monthly); not before 2024-01-01 (date_before_coverage). Category mode is monthly only. context.snapshotDate is the statistics partition actually read. Aggregates only — no review text and no reviewer identity. Billing: 1 credit per request.

  1. Use cases

Use trend to tell whether a complaint, a usage scenario or sentiment is rising or fading, and whether a burst of low ratings was a one-off. Weekly points are meaningful only for top products or larger ASIN sets. Use /voc/analysis for the full demand profile of one window (all 11 tag dimensions), and /reviews/search with dateStart/dateEnd to read the reviews behind a period. Compare two ASIN sets by calling this endpoint once per set.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[VocTrend]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modeYes'asin' for an ASIN set, 'category' for a category path. Same meaning as on /voc/analysis.
topNNoTags returned per dimension (1-30), chosen by their count over the whole window so every point reports the same tag set.
asinsNoASINs (max 100, required when mode='asin'), each in canonical form ^[A-Z0-9]{10}$ — lowercase, spaces or a site suffix are rejected with asin_must_be_normalized. The trend covers every review of the parents these ASINs belong to, not only these child ASINs; several ASINs of one parent count once. ASINs whose parent cannot be resolved are skipped — see context.resolvedAsins.
dateToNoWindow end, YYYY-MM-DD; must be given together with dateFrom. It may lie in the future: periods after today are returned as empty points.
periodNoRelative window, default '6m'. Resolved to whole months exactly as /voc/analysis does, so the same period gives both endpoints the same window ('2y' is 25 whole months). With granularity='week' only '1m', '3m' and '6m' fit the 52-week limit; '1y' and '2y' are rejected with period_limit_exceeded. Ignored when dateFrom and dateTo are given.
dateFromNoWindow start, YYYY-MM-DD; must be given together with dateTo. The window is widened outward to whole periods and may not start before 2024-01-01 (date_before_coverage).
labelTypesNoTag dimensions to return, no repeats. Defaults to ['painPoints', 'scenarios', 'buyingFactors'].
granularityNoOne point per week (Monday to Sunday, UTC) or per month. A window holds at most 25 months or 52 weeks, so 'week' works with period up to '6m'; for a longer weekly window give dateFrom/dateTo (max 52 weeks) or use 'month'. Category mode supports 'month' only; 'week' is rejected with granularity_not_supported_for_category.month
marketplaceNoAmazon marketplace code. Only 'US' is currently supported.US
categoryPathNoCategory hierarchy from root, up to 10 levels (required when mode='category'). Example: ['Electronics', 'Computers'].

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations present, the description carries the full behavioral burden and handles it exceptionally. It discloses reviewCount semantics, avgRating bias, sparse-sample lowSample flags, window widening, period granularity limits, coverage-date constraints, aggregation-only output, credit cost, and even unresolved-ASIN behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but tightly organized under 'Function' and 'Use cases', with critical caveats front-loaded. Every paragraph adds operational or interpretive information that an agent needs, and the structure makes the density navigable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex endpoint with 10 parameters and no annotations, the description is unusually complete: it covers scope rules, semantics of returned values, edge cases, error conditions, limitations, billing, and alternatives. An agent has enough guidance to choose, invoke, and interpret this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema description coverage is 100%, the prose adds substantial meaning beyond the schema: topN tags are chosen over the whole window so the tag set is consistent across points, ASIN mode expands to parent reviews, dateFrom/dateTo must be given together, granularity limits interact with period choices, and category mode supports month only. This significantly reduces ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: "Get the review and demand-tag trend," then clarifies exactly what is returned (weekly/monthly points with reviewCount, rating, sentiment, and tag shares). It also distinguishes itself from the sibling /voc/analysis and from /reviews/search by positioning the tool as the time-trend counterpart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use cases' section explicitly states when to use this tool, when to use /voc/analysis for the full demand profile, and when to use /reviews/search to read underlying reviews. It also gives practical constraints such as weekly points being meaningful only for top products or larger ASIN sets, and notes that comparing two ASIN sets requires one call per set.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All APIClaw toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources