MCP Tools
Sharing

get_share_link_activity

List tracked share links for a team or inspect one share link's open activity, approximate viewer stats, and automated opens separately without counting as an open.

Parameters

NameTypeRequiredDefaultDescription
team_idintegerYes—Team id to act in (from initialize instructions or get_current_user_info). Required on external MCP; optional in bound sessions.
share_linkstringNo—Optional share link (https://app.marcora.ai/s/<token>) or UUID token. Pass for detail mode; omit for list mode.
filterstringNo—List mode only: filter by lifetime open status.
querystringNo—List mode only: match content title (max 100 chars).
links_limitintegerNo—List mode only: links per page (1-100, default 25).
links_offsetintegerNo—List mode only: links to skip (default 0).
opens_limitintegerNo—Detail mode only: open-log rows per page (1-100, default 50).
opens_offsetintegerNo—Detail mode only: open-log rows to skip (default 0).

Input Schema

{
  "type": "object",
  "required": [
    "team_id"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "List mode only: match content title (max 100 chars)."
    },
    "filter": {
      "enum": [
        "opened",
        "not_opened"
      ],
      "type": "string",
      "description": "List mode only: filter by lifetime open status."
    },
    "team_id": {
      "type": "integer",
      "minimum": 1,
      "description": "Team id to act in (from initialize instructions or get_current_user_info). Required on external MCP; optional in bound sessions."
    },
    "share_link": {
      "type": "string",
      "description": "Optional share link (https://app.marcora.ai/s/<token>) or UUID token. Pass for detail mode; omit for list mode."
    },
    "links_limit": {
      "type": "integer",
      "default": 25,
      "maximum": 100,
      "minimum": 1,
      "description": "List mode only: links per page (1-100, default 25)."
    },
    "opens_limit": {
      "type": "integer",
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "description": "Detail mode only: open-log rows per page (1-100, default 50)."
    },
    "links_offset": {
      "type": "integer",
      "default": 0,
      "minimum": 0,
      "description": "List mode only: links to skip (default 0)."
    },
    "opens_offset": {
      "type": "integer",
      "default": 0,
      "minimum": 0,
      "description": "Detail mode only: open-log rows to skip (default 0)."
    }
  }
}

Output Schema

{
  "type": "object",
  "required": [
    "mode",
    "tracking_locked",
    "team"
  ],
  "properties": {
    "mode": {
      "enum": [
        "list",
        "detail"
      ],
      "type": "string",
      "description": "Which mode ran: list (when share_link omitted) or detail (when share_link provided)."
    },
    "team": {
      "type": "object",
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        }
      },
      "description": "The team these share links belong to."
    },
    "message": {
      "type": "string"
    },
    "links_page": {
      "type": "object",
      "required": [
        "counts",
        "summary_7d",
        "note",
        "links",
        "total",
        "limit",
        "offset"
      ],
      "properties": {
        "note": {
          "type": "string"
        },
        "limit": {
          "type": "integer"
        },
        "links": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "share_url",
              "content_id",
              "content_title",
              "status",
              "shared_at",
              "expires_at",
              "shared_by",
              "opened",
              "opens",
              "viewers",
              "last_open"
            ],
            "properties": {
              "opens": {
                "type": "integer",
                "description": "Lifetime counted opens."
              },
              "opened": {
                "type": "boolean"
              },
              "status": {
                "enum": [
                  "active",
                  "expired",
                  "off"
                ],
                "type": "string",
                "description": "active: can be opened. expired: past its expiry. off: switched off."
              },
              "viewers": {
                "type": "integer",
                "description": "People with open details only."
              },
              "last_open": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "ISO 8601."
                  },
                  "place": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "city": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "region": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "country": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    },
                    "description": "Approximate place (from the network, not the person). Any part can be null."
                  },
                  "device": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "desktop, mobile or tablet."
                  },
                  "returning": {
                    "type": "boolean"
                  }
                },
                "description": "The most recent counted open with details; null when none has details."
              },
              "share_url": {
                "type": "string"
              },
              "shared_at": {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601."
              },
              "shared_by": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Name of who created the link."
              },
              "content_id": {
                "type": "string"
              },
              "expires_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "Expiry, or null. ISO 8601."
              },
              "content_title": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        },
        "total": {
          "type": "integer",
          "description": "Links matching the filter."
        },
        "counts": {
          "type": "object",
          "properties": {
            "all": {
              "type": "integer"
            },
            "opened": {
              "type": "integer"
            },
            "not_opened": {
              "type": "integer"
            }
          }
        },
        "offset": {
          "type": "integer"
        },
        "summary_7d": {
          "type": "object",
          "properties": {
            "opens_7d": {
              "type": "integer"
            },
            "viewers_7d": {
              "type": "integer"
            },
            "not_opened_count": {
              "type": "integer",
              "description": "Active links nobody has opened."
            },
            "returning_viewers_7d": {
              "type": "integer"
            },
            "oldest_not_opened_shared_at": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "When the oldest still-unopened active link was shared. ISO 8601."
            }
          }
        }
      },
      "description": "Present in list mode when open tracking is enabled."
    },
    "link_detail": {
      "type": "object",
      "required": [
        "opened",
        "summary",
        "link",
        "opens",
        "unique_viewers",
        "opens_without_details",
        "viewers",
        "automated",
        "open_log"
      ],
      "properties": {
        "link": {
          "type": "object",
          "required": [
            "share_url",
            "status",
            "shared_at",
            "expires_at",
            "shared_by",
            "content_id",
            "content_title"
          ],
          "properties": {
            "status": {
              "enum": [
                "active",
                "expired",
                "off"
              ],
              "type": "string",
              "description": "active: can be opened. expired: past its expiry. off: switched off."
            },
            "share_url": {
              "type": "string"
            },
            "shared_at": {
              "type": "string",
              "format": "date-time",
              "description": "ISO 8601."
            },
            "shared_by": {
              "type": [
                "string",
                "null"
              ],
              "description": "Name of who created the link."
            },
            "content_id": {
              "type": "string",
              "description": "Content UUID; use with get_content."
            },
            "expires_at": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "When the link expires, or null. ISO 8601."
            },
            "content_title": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        },
        "opens": {
          "type": "integer",
          "description": "Lifetime counted opens (automated opens excluded)."
        },
        "opened": {
          "type": "boolean",
          "description": "Whether the link has been opened by anyone, from the lifetime counter."
        },
        "summary": {
          "type": "string"
        },
        "viewers": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "viewer",
              "opens",
              "first_opened_at",
              "last_opened_at",
              "place",
              "network",
              "device",
              "returning"
            ],
            "properties": {
              "opens": {
                "type": "integer"
              },
              "place": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "city": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "region": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "country": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "description": "Approximate place (from the network, not the person). Any part can be null."
              },
              "device": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "desktop, mobile or tablet."
              },
              "viewer": {
                "type": "integer",
                "description": "Viewer number, 1 = first recorded viewer identifier. Stable for this link; not a personal identity."
              },
              "network": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "kind": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "description": "The network the open came from, e.g. a company, a home ISP or a mobile carrier."
              },
              "returning": {
                "type": "boolean",
                "description": "True when this numbered viewer has more than one counted open."
              },
              "last_opened_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "When this viewer last opened it. ISO 8601."
              },
              "first_opened_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "When this viewer first opened it. ISO 8601."
              }
            }
          }
        },
        "open_log": {
          "type": "object",
          "required": [
            "total",
            "limit",
            "offset",
            "items"
          ],
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "viewed_at",
                  "device",
                  "viewer",
                  "returning",
                  "place",
                  "network",
                  "likely_automated"
                ],
                "properties": {
                  "place": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "city": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "region": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "country": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    },
                    "description": "Approximate place (from the network, not the person). Any part can be null."
                  },
                  "device": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "desktop, mobile or tablet."
                  },
                  "viewer": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "Viewer number; null for automated opens and opens with no viewer identifier."
                  },
                  "network": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "kind": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "name": {
                        "type": "string"
                      }
                    },
                    "description": "The network the open came from, e.g. a company, a home ISP or a mobile carrier."
                  },
                  "returning": {
                    "type": "boolean",
                    "description": "True when this viewer had opened the link before this open."
                  },
                  "viewed_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "ISO 8601."
                  },
                  "likely_automated": {
                    "type": "boolean",
                    "description": "True for data-center or email-scanner opens. These are never counted."
                  }
                }
              }
            },
            "limit": {
              "type": "integer"
            },
            "total": {
              "type": "integer",
              "description": "Rows in the log, automated included."
            },
            "offset": {
              "type": "integer"
            }
          }
        },
        "automated": {
          "type": "object",
          "required": [
            "opens",
            "last_at",
            "network"
          ],
          "properties": {
            "opens": {
              "type": "integer"
            },
            "last_at": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "Most recent automated open. ISO 8601."
            },
            "network": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "kind": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "name": {
                  "type": "string"
                }
              },
              "description": "The network the open came from, e.g. a company, a home ISP or a mobile carrier."
            }
          },
          "description": "Automated opens (email scanners, data centers). Not counted."
        },
        "coverage_note": {
          "type": [
            "string",
            "null"
          ],
          "description": "Set when opens lack details (opened before open details were recorded); explains what the viewer and log figures cover."
        },
        "last_opened_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Last counted open, or null if never opened. ISO 8601."
        },
        "unique_viewers": {
          "type": "integer",
          "description": "Distinct recorded viewer identifiers; excludes opens that predate open details. Not a verified count of people."
        },
        "first_opened_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "First counted open, or null if never opened. ISO 8601."
        },
        "opens_without_details": {
          "type": "integer",
          "description": "Counted opens that predate open details (no viewer, place or device). 0 when fully covered."
        }
      },
      "description": "Present in detail mode when open tracking is enabled."
    },
    "tracking_locked": {
      "type": "boolean",
      "description": "True when the team plan excludes open tracking; only `mode`, `tracking_locked`, `team`, and `message` are returned."
    }
  }
}

Instructions

Lists or inspects tracked share links for a team (Admins and Creators). Read-only: checking never counts as an open or notifies anyone.

Two modes (requires team_id):

  • List mode (omit share_link): lists links in the specified team that the caller can open, newest activity first, returning counts (all, opened, not_opened), summary_7d, and links_page (filter with filter: opened | not_opened, query, links_limit, links_offset). Cannot combine with opens_limit or opens_offset.
  • Detail mode (pass share_link: full https://app.marcora.ai/s/<token> URL or UUID token from create_external_share or list mode): returns full stats for that one link under link_detail (opened, summary, coverage_note, link, opens, unique_viewers, opens_without_details, viewers, automated, and open_log paged by opens_limit / opens_offset). Cannot combine with list parameters (filter, query, links_limit, links_offset). An invalid or malformed share_link returns an error directly (never falls back to list mode).

When to use

Someone asks which documents were shared, whether a link they sent has been opened, or wants view activity for a link.

Example prompts

  • "Which share links have been opened this week?"
  • "Has anyone opened this share link?"
  • "Show the latest opens for this link."

Access and interpreting activity

Only team Admins and Creators who can open a document can see its share activity. Teams on a plan without open tracking receive tracking_locked: true without activity. Links you cannot access and unknown links produce the same not-found response.

Opens are lifetime counts; earlier opens may have no recorded viewer, place or device. An empty viewer list does not mean the link was never opened: opens_without_details says how many and coverage_note explains it. Viewers are anonymous numbers, not identified people; one browser/device identifier need not equal one person. Place is approximate network location. Automated opens (email scanners, data centers) are listed separately under automated and flagged likely_automated in open_log; they are NOT counted in opens or viewers. Dates are ISO 8601 strings.