List a share link's opens

Returns open analytics for a share link: a summary block (the authoritative servedOpens, plus maxUses, revoked, and expiresAt) and the most recent opens, each with openedAt, clientIp, userAgent, and outcome.

Endpoint

GET https://api.dairo.app/v1/share-links/{shareLinkId}/opens

Returns open analytics for a share link: a summary block (the authoritative servedOpens, plus maxUses, revoked, and expiresAt) and the most recent opens, each with openedAt, clientIp, userAgent, and outcome. An outcome of served is a download that counts against maxUses; viewed is a non-consuming view of the share page. limit defaults to 50 and is clamped to 1–200. A share_link.opened webhook fires in real time on each open. Requires buckets:read.

Scope: buckets:read. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl "https://api.dairo.app/v1/share-links/3fa85f64-5717-4562-b3fc-2c963f66afa6/opens" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Path parameters

Name	Type	Required	Description
`shareLinkId`	string	yes	Share-link identifier (shr_*).

Query parameters

Name	Type	Required	Description
`limit`	integer	no	Max open rows (1-200, default 50). (minimum 1, maximum 200)

Response

200 Success. Body: application/json, ShareLinkOpensResponse.

Field	Type	Required
`object`	string	no
`shareLinkId`	string	no
`objectId`	string (uuid)	no
`summary`	object	no
`data`	array of object	no

200

{
  "object": "share_link_opens",
  "shareLinkId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "objectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "summary": {
    "servedOpens": 0,
    "loggedOpensReturned": 0,
    "servedInWindow": 0,
    "maxUses": null,
    "revoked": true,
    "expiresAt": "2026-10-19T09:30:00Z"
  },
  "data": [
    {
      "id": "string",
      "openedAt": "2026-10-19T09:30:00Z",
      "clientIp": null,
      "userAgent": null,
      "outcome": "served"
    }
  ]
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).