Stats Tools

Use the stats tools to read workspace, campaign, and user metrics for the workspace bound to your API key.

Available tools

Tool	Purpose
stats_get_workspace_overview	Return a workspace-level overview for a required period.
stats_get_campaign_performance	Return read-only metrics for one campaign.
stats_get_user_metrics	Return read-only metrics for one user.

stats_get_workspace_overview

Return the main workspace statistics for a required date range.

Parameters

Name	Type	Required	Description
from	String	Yes	Start date in Y-m-d format.
to	String	Yes	End date in Y-m-d format.
breakdown	String	No	One of none, day, week, month. Default: none.
workspacePublicId	String	No	Optional workspace public ID. If provided, it must match the current workspace.

Response

{
  "workspace": {
    "name": "Acme"
  },
  "period": {
    "from": "2026-03-01",
    "to": "2026-03-31"
  },
  "totals": {
    "campaignClicks": 1250,
    "vcardClicks": 310,
    "totalClicks": 1840
  },
  "breakdown": {
    "chart": {
      "datasets": {
        "current": [],
        "previous": [],
        "campaigns": []
      },
      "labels": {
        "current": [],
        "previous": []
      }
    }
  },
  "signals": [
    {
      "type": "campaign_clicks",
      "count": 1250
    }
  ],
  "generatedAt": "2026-03-28T10:25:00+00:00"
}

Field notes

• signals is a compact business summary derived from totals.

• Supported signal types are currently campaign_clicks, vcard_clicks, and other_clicks.

• generatedAt is returned in RFC 3339 format.

• When breakdown = none, breakdown is an empty object.

stats_get_campaign_performance

Return metrics for one campaign.

Parameters

Name	Type	Required	Description
campaignPublicId	String	Yes	Campaign public ID in cp_<lowercase_ulid> format.
from	String	No	Optional start date in Y-m-d format.
to	String	No	Optional end date in Y-m-d format.

Response

{
  "campaign": {
    "publicId": "cp_01hj5kq4k4a2v3x7p9m8n6c2dz",
    "name": "Spring Launch",
    "status": "running"
  },
  "period": {
    "from": "2026-02-27",
    "to": "2026-03-28"
  },
  "metrics": {
    "clicks": 1250,
    "assignedUsers": 148,
    "groups": 3
  },
  "trend": null,
  "generatedAt": "2026-03-28T10:25:00+00:00"
}

Notes

• When from and to are both omitted, the server defaults to the last 30 days ending today.

• If only one of from or to is provided, the server still falls back to the default last-30-days period.

• trend is currently always null.

stats_get_user_metrics

Return metrics for one user.

Parameters

Name	Type	Required	Description
userPublicId	String	Yes	User public ID in usr_<lowercase_ulid> format.
from	String	No	Optional start date in Y-m-d format.
to	String	No	Optional end date in Y-m-d format.

Response

{
  "user": {
    "publicId": "usr_01hj5kq4k4a2v3x7p9m8n6c2dz",
    "email": "[email protected]",
    "displayName": "John Doe",
    "status": "active"
  },
  "period": {
    "from": "2026-02-27",
    "to": "2026-03-28"
  },
  "metrics": {
    "clicks": 87,
    "campaignAssignments": 4,
    "aliases": 1
  },
  "generatedAt": "2026-03-28T10:25:00+00:00"
}

Notes

• The same 30-day default period logic applies as for stats_get_campaign_performance.

• campaignAssignments is the number of campaigns attached to the user.

• aliases is the number of aliases attached to the user.