Skip to main content
Glama

APIClaw

by io.apiclaw.api
OverviewDiscussionsAdmin

openapi_v2_product_traffic_trend_profile

Get product traffic trend profile

  1. Function

ASIN-level precomputed four-week traffic conclusions. Return traffic trend profiles for up to 20 ASINs. Only windowPeriods=[4] is currently supported and is the default when omitted. Includes impression, keyword-coverage and distribution evidence with metric directions. Items and window rows follow request order. Charge each ASIN once when at least one row has status=ok; empty profiles are free. The actual snapshot date is resolvedDate. detailLevel defaults to summary: core traffic and keyword coverage with component status, classifications, first/last values and change rates. Request full for placement/distribution breakdowns and all evidence. The mode is echoed in context.detailLevel and changes neither the query nor billing. Read items[].rows[].status (not items[].status), then component supported/calculationStatus before metrics; null is unavailable, not zero. Use trend as the overall conclusion and trendEvidence as its supporting metrics, not as a forecast or causal explanation. Impression points are estimated traffic scores, not actual impression counts. Share changes are absolute decimal differences: 0.05 means +5 percentage points; change rates are relative: 0.05 means +5%. Do not compare normalized slope magnitudes across ASINs or interpret them as percentage growth; the formula is not specified here.

Window validation failures return HTTP 422 VALIDATION_ERROR with supportedValues, suggestedValue and hint in error.details.errors; no query runs and no credits are consumed.

  1. Use cases

Summarize an ASIN's observed four-week traffic and keyword-coverage direction. Use product-traffic-trend for weekly raw data, product-traffic-structure-profile for adjacent-week structure and contributions, and detailLevel=full when detailed evidence is needed.

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[ProductTrafficTrendProfileData]",
  "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
asinNoSingle ASIN; mutually exclusive with asins.
dateYesLookup date (YYYY-MM-DD). Returns the latest profile on or before this date; see resolvedDate.
asinsNoASIN batch, up to 20; mutually exclusive with asin. Duplicates after normalization are rejected.
detailLevelNoResponse detail only; does not change the data query or billing. Default summary retains total, organic and advertising traffic and keyword coverage, component status, classifications, first/last values and change rates. full additionally includes placement/distribution breakdowns and all statistical evidence. Retry with detailLevel=full only when that extra evidence is needed; use product-traffic-trend for weekly raw data.summary
granularityNoData period granularity. Only `week` is currently supported.week
marketplaceNoAmazon marketplace code. Only 'US' is currently supported.US
windowPeriodsNoDefaults to [4]. windowPeriods must be [4] (one 4-week window). If a 4-week profile meets the task, retry with windowPeriods=[4] and the other arguments unchanged; otherwise report the supported scope.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.9/5.0
Behavior5/5

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

No annotations are provided, so the description carries the full behavioral burden; it does so thoroughly. It discloses billing behavior ('Charge each ASIN once when at least one row has status=ok; empty profiles are free'), response-reading requirements ('Read items[].rows[].status, not items[].status'), null semantics, unit semantics for share changes and change rates, the non-forecast nature of trendEvidence, and the fact that impression points are estimated traffic scores.

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 prose is front-loaded with a one-line summary and organized into Function, Use cases, and validation behavior. The lengthy caveats are dense but each earns its place because they cover billing, status semantics, units, and error conditions that are essential for correct use.

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?

Given the tool's complexity—7 parameters, batch ASINs, multiple detail levels, status hierarchy, and billing nuances—the description is complete enough for an agent to select and invoke it correctly. It covers input constraints, output interpretation, error behavior, and credit consumption, while the rich schema descriptions handle the remaining parameter-level details.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3; the description adds meaning beyond the schema by clarifying that windowPeriods=[4] is the only supported window, that detailLevel changes response content but not query or billing, and that resolvedDate is the actual snapshot date. It also gives billing and error semantics tied to parameters, which helps the agent invoke the tool correctly.

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 product traffic trend profile' and then defines the exact scope: ASIN-level precomputed four-week traffic conclusions for up to 20 ASINs. It also distinguishes this tool from closely related siblings by naming product-traffic-trend for weekly raw data and product-traffic-structure-profile for adjacent-week structure and contributions.

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?

Section 2 explicitly states the intended use case: 'Summarize an ASIN's observed four-week traffic and keyword-coverage direction.' It also gives concrete routing guidance to alternatives (product-traffic-trend, product-traffic-structure-profile, detailLevel=full) and describes when validation errors occur, so an agent can decide when to use this tool versus siblings.

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