# 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

```json
{
  "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.
* The selected period must not exceed 90 inclusive days.

## `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

```json
{
  "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 `to` is provided, `from` is inferred as 30 days before `to`.
* If only `from` is provided, `to` is inferred as today.
* `trend` is currently always `null`.
* When both `from` and `to` are provided, the selected period must not exceed 90 inclusive days.

## `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

```json
{
  "user": {
    "publicId": "usr_01hj5kq4k4a2v3x7p9m8n6c2dz",
    "email": "john.doe@example.com",
    "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.
* If only `to` is provided, `from` is inferred as 30 days before `to`.
* If only `from` is provided, `to` is inferred as today.
* When both `from` and `to` are provided, the selected period must not exceed 90 inclusive days.