Reports and Alerts
reports:read to list
and read rules, and reports:write to create, change and delete them.A rule is a scheduled report or an alert, together with where it’s sent. It’s the same
thing you build under Reports in the dashboard; see reports and
alerts for what each section and condition does.
Identify a rule by its public_id.
The API never returns destination secrets. Webhook URLs and tokens come back shortened to
their scheme and host, for example https://hooks.slack.com/….
Endpoints
| Method | Path | Scope |
|---|---|---|
GET | /api/v1/reports/rules | reports:read |
GET | /api/v1/reports/rules/{rule_public_id} | reports:read |
POST | /api/v1/reports/rules | reports:write |
PATCH | /api/v1/reports/rules/{rule_public_id} | reports:write |
DELETE | /api/v1/reports/rules/{rule_public_id} | reports:write |
You see the rules your role and teams give you access to, as in the dashboard. Owners, administrators and collaborators can create and change rules; read-only members can only read them.
List rules
| Query parameter | Notes |
|---|---|
workspace_public_id | Only rules in this workspace. A key restricted to a workspace always lists that workspace. |
schedule_types | Comma-separated: every_x for scheduled reports, event for alerts. |
link_public_ids | Comma-separated link public IDs. Only rules that cover these links. |
team_public_ids | Comma-separated team public IDs. Only rules assigned to any of these teams. |
curl "https://app.shortn.link/api/v1/reports/rules?workspace_public_id=8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10&schedule_types=every_x" \
-H "Authorization: Bearer $SHORTN_API_KEY"{
"data": [
{
"public_id": "e7b2c4a9-1f6d-4b38-9c0a-5d2e8f1b7a63",
"name": "Weekly traffic",
"workspace_public_id": "8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10",
"workspace_name": "Acme Marketing",
"team_public_id": "",
"team_name": "",
"team_public_ids": [],
"team_names": [],
"workspace_wide": true,
"schedule_type": "every_x",
"schedule_interval_seconds": 604800,
"next_run_at": "2026-11-23T08:00:00Z",
"enabled": true,
"trigger_count": 12,
"report_name": "Weekly traffic",
"report_query_type": "custom_builder_v1",
"created_at": "2026-08-17T08:00:00Z",
"destinations": [
{ "type": "email", "data": { "to": ["marketing@example.com"] } },
{ "type": "slack", "data": { "webhook_url": "https://hooks.slack.com/…" } }
]
}
]
}| Field | Notes |
|---|---|
schedule_type | every_x for a scheduled report, event for an alert. |
schedule_interval_seconds, next_run_at | A report’s interval and next run. null for alerts. |
enabled | false while the rule is paused. |
trigger_count | How many times the rule has run or fired. |
team_public_ids, workspace_wide | The teams whose links the rule covers. Empty and true when it covers the whole workspace. |
Get a rule
curl https://app.shortn.link/api/v1/reports/rules/e7b2c4a9-1f6d-4b38-9c0a-5d2e8f1b7a63 \
-H "Authorization: Bearer $SHORTN_API_KEY"{
"data": {
"public_id": "e7b2c4a9-1f6d-4b38-9c0a-5d2e8f1b7a63",
"workspace_public_id": "8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10",
"workspace_name": "Acme Marketing",
"team_public_id": "",
"team_public_ids": [],
"team_names": [],
"workspace_wide": true,
"include_unassigned_links": true,
"trigger_count": 12,
"schedule_type": "every_x",
"schedule_interval_seconds": 604800,
"next_run_at": "2026-11-23T08:00:00Z",
"enabled": true,
"report_name": "Weekly traffic",
"report_query_type": "custom_builder_v1",
"destinations": [
{ "type": "email", "data": { "to": ["marketing@example.com"] } }
],
"definition": {
"version": "custom_builder.v1",
"trigger": "scheduled",
"sections": [
{ "id": "total_clicks", "order": 1, "settings": { "window": "7d" } },
{ "id": "top_links", "order": 2, "settings": { "top_n": 10 } }
],
"filters": { "tag_public_ids": [] },
"options": { "include_comparison": true, "attach_csv": false, "locale": "en-US" }
}
}
}A single rule also returns:
definition: the sections or conditions the rule is built from;include_unassigned_links: whether it also covers links in no team;- for alerts,
watch_condition,watch_recurringandwatch_reset_increment.
To get a valid definition to send when you create rules, build the report or alert once in
the dashboard and read it here.
Create a rule
| Field | Type | Required | Notes |
|---|---|---|---|
workspace_public_id | string | Yes, unless the key is restricted to a workspace | The workspace the rule belongs to. |
report_type | string | Yes | custom_builder_v1: a report or alert built from the report library. |
schedule_type | string | No | every_x (the default) for a scheduled report, event for an alert. |
interval_seconds | integer | For reports | How often the report runs, for example 86400 (daily) or 604800 (weekly). On Free, at least 604800. |
initial_run_at | string | No | A report’s first run, in RFC 3339. Defaults to one interval from now. |
report_name | string | No | The rule’s name. |
definition_json | object | Yes | The sections or conditions. See the definition. |
destination_public_ids | array of strings | Yes, to deliver anywhere | Destinations in the workspace. |
team_public_ids | array of strings | No | Teams whose links the rule covers. Leave it out or send [] for the whole workspace. |
include_unassigned_links | boolean | No | With teams, also cover links in no team. |
link_public_ids | array of strings | No | Only cover these links. |
The teams you can pick, and who can see the rule afterwards, follow the same rules as in the dashboard (see which links a report or alert covers).
curl -X POST https://app.shortn.link/api/v1/reports/rules \
-H "Authorization: Bearer $SHORTN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_public_id": "8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10",
"report_type": "custom_builder_v1",
"schedule_type": "every_x",
"interval_seconds": 604800,
"report_name": "Weekly traffic",
"destination_public_ids": ["f2a7c9e1-5d3b-4b80-9e6a-1c4d7f0b2e35"],
"definition_json": {
"version": "custom_builder.v1",
"trigger": "scheduled",
"sections": [
{ "id": "total_clicks", "order": 1, "settings": { "window": "7d" } },
{ "id": "top_links", "order": 2, "settings": { "top_n": 10 } }
],
"options": { "include_comparison": true, "locale": "en-US" }
}
}'The response is 201, with the new rule in data, as in Get a rule. If the
rule’s details can’t be read back right away, data has only report_definition_id,
delivery_rule_id, watch_id and next_run_at.
Older single-alert report_type values are still accepted for existing integrations. New
integrations should use custom_builder_v1.
The definition
definition_json is an object with these fields:
| Field | Notes |
|---|---|
version | custom_builder.v1. |
trigger | scheduled for a report, event for an alert. |
sections | A report’s sections, in order: {"id": ..., "order": 1, "settings": {...}}. |
trigger_conditions | An alert’s conditions, with the same shape. The alert fires when any of them is met (trigger_logic: or). |
context_sections | Up to 3 sections an alert adds after its trigger. Send settings as {}. |
filters.tag_public_ids | Only cover links with these tags. |
options.locale | The language the rule is written in: en-US, es-ES, cs-CZ, fr-FR or de-DE. Defaults to your profile language. |
options.include_comparison | Compare with the previous period. |
options.attach_csv | Attach the report’s data to its emails as a CSV file. Reports only. |
Report sections:
| Category | Section IDs |
|---|---|
| Traffic | total_clicks, top_links, click_trend, peak_times, link_momentum, referrer_breakdown, utm_breakdown, qr_scans |
| Audience | geo_breakdown, device_mix, language_mix, traffic_quality |
| Revenue | conversions_summary, top_converting_links, commissions_summary, partner_payouts |
| Links | tag_performance, team_performance, inactive_links, ab_tests, link_activity, upcoming_links |
| Health & security | health_snapshot, quota_snapshot, abuse_reports, destination_security, domain_status, conversion_connectors |
| Workspace | workspace_changes |
Most sections take a window setting: 24h, 7d, 14d, 30d or 90d. Without it, a
section reads the report’s interval. Ranked sections take top_n.
Alert conditions:
| Condition ID | Settings the dashboard starts with |
|---|---|
link_click_threshold | {"threshold": 1000, "recurring": true} |
traffic_change | {"direction": "increase", "window_minutes": 15, "change_percent": 100, "min_clicks": 20, "cooldown_minutes": 60} |
unexpected_geo | {"window_minutes": 30, "baseline_days": 7, "min_window_clicks": 20, "min_country_clicks": 5, "ignore_unknown": true, "cooldown_minutes": 180} |
qr_scan_milestone | {"threshold": 100, "recurring": true} |
link_health_changed | {"status_code_groups": ["4xx", "5xx"]} |
link_expiration_warning | {"warning_presets": [24]} |
link_expired, link_status_changed, link_scheduled_live, link_destination_changed | {} |
link_abuse_reported | {"review_outcomes": "none"} |
bot_traffic_surge | {"window_minutes": 60, "bot_share_percent": 50, "min_clicks": 50, "cooldown_minutes": 180} |
link_conversion | {"event_types": "sales", "cooldown_minutes": 0} |
link_refund | {"refunds": "all", "cooldown_minutes": 0} |
commission_pending, conversion_connector_issue, ab_test_ready | {} |
workspace_usage_quota_alert | {"active_links_percent": 80, "tracked_clicks_percent": 80, "repeat_interval": "once"} |
workspace_domain_issue | {"issues": "both"} |
workspace_member_changed | {"changes": "both"} |
An alert definition:
{
"version": "custom_builder.v1",
"trigger": "event",
"trigger_logic": "or",
"trigger_conditions": [
{ "id": "link_click_threshold", "order": 1, "settings": { "threshold": 1000, "recurring": true } }
],
"context_sections": [
{ "id": "top_links", "order": 1, "settings": {} }
],
"options": { "locale": "en-US" }
}Update a rule
PATCH changes what you send and keeps the rest. Send the fields as when
creating.
- Pause or resume: send only
{"enabled": false}or{"enabled": true}. Resuming a rule checks your plan’s rule limit again. - New interval: a new
interval_secondswithoutinitial_run_atmoves the next run to one new interval from now, unless the run already planned is sooner. - Destinations: the API returns destinations with their secrets shortened. To change
them, send
destination_public_ids, or leave destinations out to keep them. Sending a shortened value back returns400destination_secret_redacted. - Workspace: a rule can’t move to another workspace. Create a new rule there instead.
curl -X PATCH https://app.shortn.link/api/v1/reports/rules/e7b2c4a9-1f6d-4b38-9c0a-5d2e8f1b7a63 \
-H "Authorization: Bearer $SHORTN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'The response is the rule in data, with the fields of List rules.
Delete a rule
curl -X DELETE https://app.shortn.link/api/v1/reports/rules/e7b2c4a9-1f6d-4b38-9c0a-5d2e8f1b7a63 \
-H "Authorization: Bearer $SHORTN_API_KEY"The response is 204 with no body.
Plan limits
Plan limits return 403 with code plan_limit_exceeded and feature
report_alert_rules:
error | required_plan |
|---|---|
| Triggered alerts are available on the Starter plan or higher | starter |
| Free plan scheduled reports can run at most once per week | starter |
| Report and alert rule limit reached for your current plan | null, with limit and current |
The limit counts the enabled rules you created; paused rules don’t count. A destination type
your plan doesn’t include returns 403 with feature webhooks_integrations (see
destinations).
Errors
| Status | code | When |
|---|---|---|
400 | invalid_request | The body isn’t valid JSON. |
400 | workspace_required | workspace_public_id is missing. |
400 | invalid_report_rule | The reporting service refused the rule. error says why, for example interval_seconds is required. |
400 | workspace_move_not_supported | The update names another workspace. |
400 | destination_secret_redacted | A destination still holds a shortened secret. |
403 | workspace_permission_denied | You’re a read-only member. |
403 | api_key_workspace_mismatch | The workspace or rule is outside the key’s workspace. |
403 | plan_limit_exceeded | See plan limits. |
404 | workspace_not_found | The workspace doesn’t exist, is archived, or you aren’t a member. |
404 | report_rule_not_found | No rule with this ID that you can see. |
409 | workspace_archived | The rule’s workspace is archived. |
502 | report_delete_failed | The rule couldn’t be deleted. Try again. |
503 | reports_unavailable | The reporting service is unavailable. Try again in a few minutes. |
Errors every endpoint can return (a missing key, a missing scope, rate limits) are listed on authentication.