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
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
team_id | integer | Yes | — | Team id to act in (from initialize instructions or get_current_user_info). Required on external MCP; optional in bound sessions. |
share_link | string | No | — | Optional share link (https://app.marcora.ai/s/<token>) or UUID token. Pass for detail mode; omit for list mode. |
filter | string | No | — | List mode only: filter by lifetime open status. |
query | string | No | — | List mode only: match content title (max 100 chars). |
links_limit | integer | No | — | List mode only: links per page (1-100, default 25). |
links_offset | integer | No | — | List mode only: links to skip (default 0). |
opens_limit | integer | No | — | Detail mode only: open-log rows per page (1-100, default 50). |
opens_offset | integer | No | — | 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, returningcounts(all,opened,not_opened),summary_7d, andlinks_page(filter withfilter:opened|not_opened,query,links_limit,links_offset). Cannot combine withopens_limitoropens_offset. - Detail mode (pass
share_link: fullhttps://app.marcora.ai/s/<token>URL or UUID token fromcreate_external_shareor list mode): returns full stats for that one link underlink_detail(opened,summary,coverage_note,link,opens,unique_viewers,opens_without_details,viewers,automated, andopen_logpaged byopens_limit/opens_offset). Cannot combine with list parameters (filter,query,links_limit,links_offset). An invalid or malformedshare_linkreturns 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.