pinbridge

Get pin analytics

get_pin_analytics

Read-onlyIdempotent

Pinterest performance metrics for one published pin over a date range.

    Use after a pin has been published for a while to report impressions,
    saves and clicks. For the whole account use get_account_analytics; for
    publish status use get_pin.

    Returns pin_id, pinterest_pin_id, account_id, start_date, end_date,
    provider_mode, totals (each metric summed over the range, lowercase
    names), daily rows (empty with include_daily=false; pass that when the
    totals are enough), source (stored or live) and data_as_of for stored
    reads. total_comments and total_reactions are lifetime counts on live
    reads and 0 on stored reads, which do not keep them: use source=live
    for comments and reactions. They read 0 on every daily row, since
    Pinterest does not report them per day. A pin deleted on Pinterest is answered from stored
    history with removed_from_pinterest_at set, and fails with
    pin_removed_on_pinterest when none is stored. Fails with not_found for
    an unknown pin and with pin_not_published for a pin that has not
    published yet; sandbox pins return zeroed metrics.

Input Schema

TableJSON Schema

Name	Required	Description
`pin_id`	Yes	UUID of the pin, from list_pins or create_pin.
`source`	No	Where to read from. auto (default): PinBridge's nightly stored history when it covers the range, else Pinterest. stored: history only (up to 366 days). live: always ask Pinterest (up to 90 days, counts against the read limit).
`metrics`	No	Comma-separated Pinterest metric types, e.g. IMPRESSION,SAVE,PIN_CLICK,OUTBOUND_CLICK. Default: the organic engagement set.
`end_date`	No	Inclusive end, YYYY-MM-DD. Default: today. Up to 366 days from stored history, 90 days when read live from Pinterest.
`start_date`	No	Inclusive start, YYYY-MM-DD. Default: 30 days ago.
`include_daily`	No	false: return only the range totals, with an empty daily list. Use it when the totals are all you need, e.g. over 90 days. Default: true.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 26, 2026

addedInput schema / properties / include_daily

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "false: return only the range totals, with an empty daily list. Use it when the totals are all you need, e.g. over 90 days. Default: true.",
+  "title": "Include Daily"
+}

Changed2 schema fields changedSep 25, 2026

changedInput schema / properties / end_date / description

Previous value: -"Inclusive end, YYYY-MM-DD. Default: today. Ranges are capped at 90 days."New value: +"Inclusive end, YYYY-MM-DD. Default: today. Up to 366 days from stored history, 90 days when read live from Pinterest."

addedInput schema / properties / source

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "auto",
+        "stored",
+        "live"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Where to read from. auto (default): PinBridge's nightly stored history when it covers the range, else Pinterest. stored: history only (up to 366 days). live: always ask Pinterest (up to 90 days, counts against the read limit).",
+  "title": "Source"
+}

Changed4 schema fields changedSep 24, 2026

addedInput schema / properties / end_date / description

Added value: +"Inclusive end, YYYY-MM-DD. Default: today. Ranges are capped at 90 days."

addedInput schema / properties / metrics / description

Added value: +"Comma-separated Pinterest metric types, e.g. IMPRESSION,SAVE,PIN_CLICK,OUTBOUND_CLICK. Default: the organic engagement set."

addedInput schema / properties / pin_id / description

Added value: +"UUID of the pin, from list_pins or create_pin."

addedInput schema / properties / start_date / description

Added value: +"Inclusive start, YYYY-MM-DD. Default: 30 days ago."

AddedSep 24, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already mark the tool as readOnly and idempotent, but the description goes well beyond: it explains stored vs live reads, zeroed daily metrics, lifetime counts for comments/reactions, deleted-pin fallback behavior, specific error cases, and sandbox behavior. There is no contradiction with the annotations.

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 appropriately sized for a six-parameter read tool with no output schema. It is front-loaded with purpose and usage, then return fields, then exceptions. Each clause carries distinguishing information rather than padding.

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?

With no output schema, the description supplies the return field list, daily-row behavior, source semantics, and failure modes. Combined with the fully documented input schema, an agent has everything needed to invoke and interpret the tool correctly.

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 coverage is 100%, so the baseline is 3, but the description adds decision-relevant meaning beyond the schema: use source=live for comments and reactions, pass include_daily=false when totals suffice, and the implications of stored history vs live reads. Metrics and date syntax are already fully covered by the schema.

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: 'Pinterest performance metrics for one published pin over a date range.' It also explicitly distinguishes itself from get_account_analytics and get_pin, so an agent can tell which tool to choose among many siblings.

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?

It gives explicit timing ('Use after a pin has been published for a while'), names the alternatives for account-level metrics and publish status, and even advises when to pass include_daily=false. This is clear, actionable when-to-use guidance.

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

All pinbridge tools Inspect

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

Need Help?